Speed, Pause, Pronunciation

Flux TTS (/v2/speak) voice controls let you adjust speech output: change the speaking rate, insert silence, and override the pronunciation of specific words. They are designed for use cases that need precise delivery of industry terminology, brand names, and complex content.

Aura-2 (/v1/speak) supports speed and pronunciation with the same syntax. Each section calls out where Aura-2 differs.

Availability

Flux TTS controls are available in English. Aura-2 speed and pronunciation are available in English and Spanish.

Speed control

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

Parameters

On a streaming session, set speed as a connection parameter or change it mid-session with a Configure message. The change applies at the next segment boundary.

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/v2/speak?model=flux-haley-en&speed=0.9"

Speed values

A value outside the range, or inside it but off the 0.05 increment, returns an error.

Pause control

Insert silence at a specific point in the text. Pause control is available on Flux TTS batch requests.

Syntax

Place an escaped pause marker where you want the silence:

Your confirmation number is 4 7 2. \{pause:1s\} Is there anything else I can help with?

Write the duration in milliseconds (\{pause:500\} or \{pause:500ms\}) or seconds (\{pause:1.5s\}). A number with no unit is read as milliseconds. A structured form, {pause:{duration_ms:500}}, is also accepted and is easier for LLMs to generate. Write the structured form without backslashes; an escaped structured marker, or a simple marker without backslashes, is rejected with BREAK_SYNTAX_INVALID.

Example request

curl --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Token DEEPGRAM_API_KEY" \
     --output your_output_file.mp3 \
     --data '{"text":"Your confirmation number is 4 7 2. \\{pause:1s\\} Is there anything else I can help with?"}' \
     --url "https://api.deepgram.com/v2/speak?model=flux-haley-en"

Validation rules

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 \})

Writing IPA for Flux TTS

Flux TTS was trained on a specific IPA style. Overrides that follow it are applied more reliably:

• Use broad (phonemic) transcription, for example kˈɑpiɹˌaɪt (copyright). Leave out narrow phonetic detail.
• Use American pronunciations. The model was trained mostly on American English.
• Always mark primary stress with ˈ. Nearly every word the model was trained on carries one. You can place it before the syllable (ˈkɑpi) or directly before the vowel (kˈɑpi).
• Secondary stress is optional. Add ˌ when you want more control over a long word.
• Use ɹ for the English r sound, not r.
• Add length markers where the model slips. If a vowel comes out short or swapped, mark it long: -miːn rather than -min.

Example request

curl -X POST "https://api.deepgram.com/v2/speak?model=flux-haley-en" \
     -H "Authorization: token DEEPGRAM_API_KEY" \
     -H "Content-Type: application/json" \
     --output your_output_file.mp3 \
     -d '{"text": "Take \\{\"word\": \"Azathioprine\", \"pronounce\": \"æzəˈθaɪəpɹiː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

A speed of exactly 1.0 does not count as a speed control, so it never triggers these rules. On a streaming session, a pronunciation control sent on a connection opened with a speed other than 1.0, or after a Configure that set one, fails the connection with DATA-0002. A mid-stream Configure that sets speed while a queued turn still carries a pronunciation control is refused with a ConfigureFailure (CONTROL_COMBINATION_INVALID), and the previous speed stays in force. Pronunciations in the turn that is already playing do not block it. See ConfigureFailure codes.

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 medical_instructions.mp3 \
     -d '{"text": "Take \\{\"word\": \"Azathioprine\", \"pronounce\": \"æzəˈθaɪəpɹiːn\"\\} twice daily."}'

Healthcare example

This example uses pronunciation control, which is in Early Access on Flux TTS.

curl -X POST "https://api.deepgram.com/v2/speak?model=flux-haley-en" \
     -H "Authorization: token DEEPGRAM_API_KEY" \
     -H "Content-Type: application/json" \
     --output medical_instructions.mp3 \
     -d '{"text": "Take \\{\"word\": \"Azathioprine\", \"pronounce\": \"æzəˈθaɪəpɹiːn\"\\} twice daily with \\{\"word\": \"dupilumab\", \"pronounce\": \"duːˈpɪljuːmæb\"\\}."}'

Appointment reminder example

Speed and pause can be combined as long as speed stays at or below 1.15.

curl -X POST "https://api.deepgram.com/v2/speak?model=flux-haley-en&speed=0.9" \
     -H "Authorization: token DEEPGRAM_API_KEY" \
     -H "Content-Type: application/json" \
     --output appointment_reminder.mp3 \
     -d '{"text": "Your appointment is on Tuesday at 3 PM. \\{pause:800ms\\} Reply YES to confirm."}'

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)

Reporting applied controls

Batch response headers

Batch requests report applied controls in the response headers. Flux TTS (/v2/speak) and Aura-2 (/v1/speak) return the same headers.

HTTP/1.1 200 OK
content-type: audio/mpeg
dg-request-id: 3f2a9c1e-8b4d-4e2a-9f1c-7d6e5b4a3c21
dg-model-name: flux-haley-en
dg-char-count: 47
dg-pronunciations-applied: 2
dg-breaks-applied: 0

The response does not echo the speed value; it is the value you sent in the request.

Streaming

On a streaming session, each turn’s SpeechMetadata reports controls_applied: pronunciations_applied, breaks_applied, and pronunciation_warnings.

A pronunciation override that triggers an IPA warning is still applied best-effort and counted in pronunciations_applied; the warning is reported separately. Listen to any term that produced a warning before you ship it.

Pronunciation warning codes

Batch requests list these codes in dg-warnings. On a streaming session, the same conditions produce a PRONUNCIATION_WARNINGS Warning.

Error handling

Batch requests return a 400 with one of these err_code values:

Invalid IPA and invalid speed values are also rejected. On a streaming session, see the warning, ConfigureFailure, and error codes.

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

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

Limits