Text To Speech REST — Deepgram

The Deepgram Speak Clients allows you to generate human-like audio from text.

This SDK supports both the Threaded and Async/Await Clients as described in the Threaded and Async IO Task Support section. The code blocks contain a tab for Threaded and Async to show examples for rest versus asyncrest, respectively. The difference between Threaded and Async is subtle.

Installing the SDK

Python

1 # Install the Deepgram Python SDK
2 # https://github.com/deepgram/deepgram-python-sdk
3 
4 pip install deepgram-sdk==3.*

Make a Deepgram Text-to-Speech Request

The Deepgram Speak Clients allow you to create audio generated from provided text, also known as text-to-speech.

There are two functions provided to translate text-to-speech:

stream() - This takes the resulting audio and holds it in memory via io.BytesIO.
save() or file() - These save the audio stream to a user provided filename.

1 import os
2 from deepgram import DeepgramClient, SpeakOptions
3 
4 SPEAK_OPTIONS = {"text": "Hello, how can I help you today?"}
5 filename = "output.mp3"
6 
7 def main():
8     try:
9         # STEP 1: Create a Deepgram client.
10         # By default, the DEEPGRAM_API_KEY environment variable will be used for the API Key
11         deepgram = DeepgramClient()
12 
13         # STEP 2: Configure the options (such as model choice, audio configuration, etc.)
14         options = SpeakOptions(
15             model="aura-asteria-en",
16         )
17 
18         # STEP 3: Call the save method on the speak property
19         response = deepgram.speak.rest.v("1").save(filename, SPEAK_OPTIONS, options)
20         print(response.to_json(indent=4))
21 
22     except Exception as e:
23         print(f"Exception: {e}")
24 
25 if __name__ == "__main__":
26     main()

Audio Output Streaming

Deepgram’s TTS API allows you to start playing the audio once the first byte is received. This section provides examples to help you stream the audio output efficiently.

Single Text Source Payload

The following example demonstrates how to stream the audio as soon as the first byte arrives for a single text source.

Threaded

1 import re
2 from deepgram import Deepgram
3 import requests
4 
5 DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'
6 deepgram = Deepgram(DEEPGRAM_API_KEY)
7 
8 inputText = "Your long text goes here..."
9 
10 def segmentTextBySentence(text):
11     return re.findall(r"[^.!?]+[.!?]", text)
12 
13 def synthesizeAudio(text):
14     options = SpeakOptions(
15         model="aura-asteria-en",
16     )
17 
18     response = deepgram.speak.rest.v("1").stream(filename, SPEAK_OPTIONS, options)
19 
20     if response.status_code == 200:
21         return response.content
22     else:
23         raise Exception('Error generating audio')
24 
25 def main():
26     segments = segmentTextBySentence(inputText)
27 
28     for i, segment in enumerate(segments):
29         try:
30             audioData = synthesizeAudio(segment)
31             with open(f"output_{i}.wav", 'wb') as f:
32                 f.write(audioData)
33             print(f"Audio stream finished for segment: {segment}")
34         except Exception as error:
35             print(f"Error synthesizing audio: {error}")
36 
37     print("Audio file creation completed.")
38 
39 main()

Chunked Text Source Payload

This example shows how to chunk the text source by sentence boundaries and stream the audio for each chunk consecutively.

Threaded

1 import re
2 from deepgram import Deepgram
3 import requests
4 
5 DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'
6 deepgram = Deepgram(DEEPGRAM_API_KEY)
7 
8 inputText = "Your long text goes here..."
9 
10 def segmentTextBySentence(text):
11     return re.findall(r"[^.!?]+[.!?]", text)
12 
13 def synthesizeAudio(text):
14     options = SpeakOptions(
15         model="aura-asteria-en",
16     )
17 
18     response = deepgram.speak.rest.v("1").stream(filename, SPEAK_OPTIONS, options)
19 
20     if response.status_code == 200:
21         return response.content
22     else:
23         raise Exception('Error generating audio')
24 
25 def main():
26     segments = segmentTextBySentence(inputText)
27 
28     for i, segment in enumerate(segments):
29         try:
30             audioData = synthesizeAudio(segment)
31             with open(f"output_{{i}}.wav", 'wb') as f:
32                 f.write(audioData)
33             print(f"Audio stream finished for segment: {{segment}}")
34         except Exception as error:
35             print(f"Error synthesizing audio: {{error}}")
36 
37     print("Audio file creation completed.")
38 
39 main()

Where to Find Additional Examples

The SDK repository has a good collection of text-to-speech examples. The README contains links to them. Each example below attempts to provide different options for transcribing an audio source.

Some Examples:

Threaded Client speaking “Hello World” - examples/text-to-speech/rest/file/hello_world

If the Async Client suits your use case better:

Threaded Client speaking “Hello World” - examples/text-to-speech/rest/file/async_hello_world

1	# Install the Deepgram Python SDK
2	# https://github.com/deepgram/deepgram-python-sdk
3
4	pip install deepgram-sdk==3.*

1	import os
2	from deepgram import DeepgramClient, SpeakOptions
3
4	SPEAK_OPTIONS = {"text": "Hello, how can I help you today?"}
5	filename = "output.mp3"
6
7	def main():
8	try:
9	# STEP 1: Create a Deepgram client.
10	# By default, the DEEPGRAM_API_KEY environment variable will be used for the API Key
11	deepgram = DeepgramClient()
12
13	# STEP 2: Configure the options (such as model choice, audio configuration, etc.)
14	options = SpeakOptions(
15	model="aura-asteria-en",
16	)
17
18	# STEP 3: Call the save method on the speak property
19	response = deepgram.speak.rest.v("1").save(filename, SPEAK_OPTIONS, options)
20	print(response.to_json(indent=4))
21
22	except Exception as e:
23	print(f"Exception: {e}")
24
25	if __name__ == "__main__":
26	main()

1	import re
2	from deepgram import Deepgram
3	import requests
4
5	DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'
6	deepgram = Deepgram(DEEPGRAM_API_KEY)
7
8	inputText = "Your long text goes here..."
9
10	def segmentTextBySentence(text):
11	return re.findall(r"[^.!?]+[.!?]", text)
12
13	def synthesizeAudio(text):
14	options = SpeakOptions(
15	model="aura-asteria-en",
16	)
17
18	response = deepgram.speak.rest.v("1").stream(filename, SPEAK_OPTIONS, options)
19
20	if response.status_code == 200:
21	return response.content
22	else:
23	raise Exception('Error generating audio')
24
25	def main():
26	segments = segmentTextBySentence(inputText)
27
28	for i, segment in enumerate(segments):
29	try:
30	audioData = synthesizeAudio(segment)
31	with open(f"output_{i}.wav", 'wb') as f:
32	f.write(audioData)
33	print(f"Audio stream finished for segment: {segment}")
34	except Exception as error:
35	print(f"Error synthesizing audio: {error}")
36
37	print("Audio file creation completed.")
38
39	main()