Getting Started

This guide will walk you through how to turn text into speech with Deepgram’s text-to-speech REST API.

API Playground

First, quickly explore Deepgram Text to Speech in our API Playground.

CURL

Next, try it with CURL. Add your own API key where it says YOUR_DEEPGRAM_API_KEY and then run the following example in a terminal or your favorite API client.

$
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-asteria-en"

This will result in an MP3 audio file being streamed back to you by Deepgram. You can play the audio as soon as you receive the first byte, or you can wait until the entire MP3 file has arrived.

The audio file will contain the voice of the selected model saying the words that you sent in your request.

Send Error Messages to Terminal

If your request results in an error, the error message can be seen by opening the output audio file in a text editor.

To see the error message in your terminal, add this to your CURL request:

$
--fail-with-body \
>
--silent \
>
|| (jq . your_output_file.mp3 && rm your_output_file.mp3)

This example will capture the error message using jq and remove the output file (tts.mp3) automatically.

$
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=testing_error' \
>
     --fail-with-body \
>
     --silent \
>
     || (jq . your_output_file.mp3 && rm your_output_file.mp3)

SDKs

Deepgram has several SDKs that can make it easier to use the API. Follow these steps to use the SDK of your choice to make a Deepgram TTS request.

Install the SDK

Open your terminal, navigate to the location on your drive where you want to create your project, and install the Deepgram SDK.

$
# Install the Deepgram JS SDK
>
# https://github.com/deepgram/deepgram-js-sdk
>
>
npm install @deepgram/sdk

Add Dependencies

$
# Install dotenv to protect your api key
>
>
npm install dotenv

Make the Request with the SDK

1
const { createClient } = require("@deepgram/sdk");
2
const fs = require("fs");
3
4
// STEP 1: Create a Deepgram client with your API key
5
const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
6
7
const text = "Hello, how can I help you today?";
8
9
const getAudio = async () => {
10
  // STEP 2: Make a request and configure the request with options (such as model choice, audio configuration, etc.)
11
  const response = await deepgram.speak.request(
12
    { text },
13
    {
14
      model: "aura-asteria-en",
15
      encoding: "linear16",
16
      container: "wav",
17
    }
18
  );
19
  // STEP 3: Get the audio stream and headers from the response
20
  const stream = await response.getStream();
21
  const headers = await response.getHeaders();
22
  if (stream) {
23
    // STEP 4: Convert the stream to an audio buffer
24
    const buffer = await getAudioBuffer(stream);
25
    // STEP 5: Write the audio buffer to a file
26
    fs.writeFile("output.wav", buffer, (err) => {
27
      if (err) {
28
        console.error("Error writing audio to file:", err);
29
      } else {
30
        console.log("Audio file written to output.wav");
31
      }
32
    });
33
  } else {
34
    console.error("Error generating audio:", stream);
35
  }
36
37
  if (headers) {
38
    console.log("Headers:", headers);
39
  }
40
};
41
42
// helper function to convert stream to audio buffer
43
const getAudioBuffer = async (response) => {
44
  const reader = response.getReader();
45
  const chunks = [];
46
47
  while (true) {
48
    const { done, value } = await reader.read();
49
    if (done) break;
50
51
    chunks.push(value);
52
  }
53
54
  const dataArray = chunks.reduce(
55
    (acc, chunk) => Uint8Array.from([...acc, ...chunk]),
56
    new Uint8Array(0)
57
  );
58
59
  return Buffer.from(dataArray.buffer);
60
};
61
62
getAudio();

Non-SDK Code Examples

If you would like to try out making a Deepgram speech-to-text request in a specific language (but not using Deepgram’s SDKs), we offer a library of code-samples in this Github repo. However, we recommend first trying out our SDKs, which we presented in the previous section.

Results

Upon successful processing of the request, you will receive an audio file containing the synthesized text-to-speech output, along with response headers providing additional information.

Example Response Headers

HTTP/1.1 200 OK
< content-type: audio/mpeg
< dg-model-name: aura-asteria-en
< dg-model-uuid: e4979ab0-8475-4901-9d66-0a562a4949bb
< dg-char-count: 32
< dg-request-id: bf6fc5c7-8f84-479f-b70a-602cf5bf18f3
< transfer-encoding: chunked
< date: Thu, 29 Feb 2024 19:20:48 GMT

This includes:

• content-type: Specifies the media type of the resource, in this case, audio/mpeg, indicating the format of the audio file returned.
• dg-request-id: A unique identifier for the request, useful for debugging and tracking purposes.
• dg-model-uuid: The unique identifier of the model that processed the request.
• dg-char-count: Indicates the number of characters that were in the input text for the text-to-speech process.
• dg-model-name: The name of the model used to process the request.
• transfer-encoding: Specifies the form of encoding used to safely transfer the payload to the recipient.
• date: The date and time the response was sent.

Limits

Keep these limits in mind when making a Deepgram text-to-speech request.

Input Text Limit

• Maximum characters: 2000.
• Sending a text payload longer than 2000 characters (2001 or more) will result in an error, and the audio file will not be created.

Rate Limits

• Pay As You Go Plan: 480 requests per minute.
• Growth Plan: 720 requests per minute.

Handling Rate Limits

• If the number of in-progress requests for a project meets or exceeds the rate limit, new requests will receive a 429: Too Many Requests error.
• With a typical response time of 250ms, users of our Pay As You Go or Growth plans can achieve a request rate of roughly:
  2 (concurrent requests) / 0.250 (250 ms response time) * 60 (seconds/minute) = 480 requests per minute.

What’s Next?

Now that you’ve transformed text into speech with Deepgram’s API, enhance your knowledge by exploring the following areas.

Starter Apps

• Clone and run one of our Starter App repositories to see a full application with a frontend UI and a backend server sending text to Deepgram to be converted into audio.

Read the Feature Guides

Deepgram’s features help you to customize your request to produce the output that works best for your use case.

• Media Output Settings: Learn how to customize the audio file that is returned.
• Callback: Discover how to provide a callback url, so that your audio can be processed asynchronously.
• Feature Overview: Review the list of features available for pre-recorded speech-to-text. Then, dive into individual guides for more details.

Transcribe Speech-to-Text

• Check out how you can use Deepgram to turn audio into text. Read the Pre-Recorded Speech-To-Text guide or the Streaming Speech-To-Text Guide.

Try the Conversational AI Demo

• The purpose of this demo is to showcase how you can build a Conversational AI application that engages users in natural language interactions, mimicking human conversation through natural language processing using Deepgram and OpenAI ChatGPT.

Watch This Video

• See how you can use Deepgram Aura with Groq to build a blazing fast Conversational AI application.