TTS Callback

callback string

Text to Speech Request Text to Speech Stream English Only

Deepgram’s Callback feature allows you to supply a callback URL to which generated text-to-speech audio can be returned. When passed, Deepgram will immediately respond with a request_id before processing your text asynchronously.

To enable Callback, when you call Deepgram’s API, add a callback parameter in the query string and set it to the URL to which you would like transcriptions sent:

callback=URL

To synthesize text-to-speech and generate an audio file, run the following cURL command in a terminal or your favorite API client:

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

An example URL is https://example.com/callback.

Your callback URLs may reference the http or https protocols.

Authentication ensures the security and integrity of callback requests. There are two main methods for authenticating callback requests: using Basic Auth and utilizing the dg-token request header.

You may embed username-password authentication credentials in the callback URL in the format https://username:[email protected]. However, it’s important to note that only ports 80, 443, 8080, and 8443 are permitted for callbacks.

Alternatively, the callback request itself contains a header named dg-token. This header is automatically set to the API Key Identifier associated with the API Key used to submit the original request. This method provides a secure and straightforward means of authentication.

When Deepgram has finished analyzing the text, it will send a POST request to the provided callback URL with an appropriate HTTP status code.

If the HTTP status code of the response to the callback POST request is unsuccessful (not 200-299), Deepgram will retry the callback up to 10 times with a 30 second delay between attempts.

To enable the Callback Method, include the callback_method parameter in the query string. By default, the method supports POST, but you can specify PUT instead.

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: text/plain' \
  --data 'Your Text.' \
  --url 'https://api.deepgram.com/v1/speak?callback=URL&callback_method=put'