For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Ask AIPlaygroundLoginFree API Key
HomeAPI ReferenceVoice AgentSpeech-to-TextText-to-SpeechIntelligenceSelf-Hosted Deployments
HomeAPI ReferenceVoice AgentSpeech-to-TextText-to-SpeechIntelligenceSelf-Hosted Deployments
  • Text-to-Speech REST
    • Getting Started
    • Feature Overview
    • Template Apps
  • Text-to-Speech Streaming
    • Getting Started
    • Feature Overview
    • Template Apps
  • Models and Languages
    • Voices and Languages
    • TTS Voice Controls
  • Media Output Settings
    • Encoding
    • Bit Rate
    • Container
    • Sample Rate
  • Results Processing
    • TTS Tagging
    • TTS Callback
    • Audio Output Streaming
  • Tips and Tricks
    • Real-Time TTS with WebSockets
    • Text Chunking for TTS
    • Formatting text for Aura-2
    • Handling Audio Issues in Text To Speech
    • Sending LLM Outputs to a WebSocket
    • Text Chunking for TTS REST Optimization
    • Text to Speech Latency
    • Text to Speech Prompting
    • TTS Troubleshooting WebSocket, NET, and DATA Errors
LogoLogo
Ask AIPlaygroundLoginFree API Key
On this page
  • Enable Feature
  • URL Structure
  • Authenticating Callback Requests
  • Using Basic Auth
  • Using the dg-token Request Header
  • Results
  • Using CallBack_Method
Results Processing

TTS Callback

A text-to-speech Callback allows you to have your submitted text processed asynchronously.

Was this page helpful?
Previous

Audio Output Streaming

Start streaming your text-to-speech REST audio as soon as the first byte arrives.

Next
Built with

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.

Enable Feature

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
$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'

URL Structure

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

Your callback URLs may reference the http or https protocols.

Authenticating Callback Requests

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.

Using Basic Auth

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.

Only ports 80, 443, 8080, and 8443 are permitted for callbacks.

Using the dg-token Request Header

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.

Results

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.

Using CallBack_Method

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
$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'