Callback
Learn about Deepgram's Callback feature, which allows you to have your submitted audio processed asynchronously.
Deepgram’s Callback feature allows you to supply a callback URL to which transcriptions can be returned. When passed, Deepgram will immediately respond with a request_id
before processing your audio asynchronously.
Use Cases
Some examples of use cases for Callback include:
- Customers with large amounts of audio that may be slow to process.
- Customers who don't require immediate results.
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 transcribe audio from a file on your computer, run the following cURL command in a terminal or your favorite API client.
Be sure to replace the placeholder
URL
with your chosen callback URL andYOUR_DEEPGRAM_API_KEY
with your Deepgram API Key. You can create an API Key in the Deepgram Console.
curl \
--request POST \
--header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
--header 'Content-Type: audio/wav' \
--data-binary @youraudio.wav \
--url 'https://api.deepgram.com/v1/listen?callback=URL'
URL Structure
An example URL is https://example.com/callback
.
Your callback URLs may reference the following protocols:
- For pre-recorded audio:
http
orhttps
- For streaming audio,
http
,https
,ws
, orwss:
You may embed basic authentication credentials in the callback URL.
Only ports 80, 443, 8080, and 8443 may be used for callbacks.
Results
Depending on the type of submitted audio, the response will vary.
Pre-recorded Audio
When Deepgram has finished analyzing the audio, 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.
If you would like Deepgram to make a PUT
request rather than a POST
request to your callback URL, you can add the callback_method=PUT
query parameter in addition to callback=URL
.
Streaming Audio
As Deepgram analyzes the audio, the way in which it sends requests back to the provided callback URL varies:
- If your callback URL begins with
http://
orhttps://
, then Deepgram will sendPOST
requests to the callback server for each streaming response. - If your callback URL begins with
ws://
orwss://
, then Deepgram will establish a WebSocket connection with the callback server and send WebSocket text messages that contain the streaming responses.
If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.
Updated 9 days ago