free
hit counters

Deepgram API: Getting Started

Here we have some instructions on how to work with the Deepgram API. The instructions are given sequentially, so you can easily get your own API key and follow along.

Once you have generated your key, you can test with a single file (we use a file already hosted on the web for this guide). We run through a few API calls and note their outputs to help demonstrate how the system works.

We hope that this gives you all the things you need to make testing with your own files a breeze! Let us know if you have any questions or suggestions. We'd love to hear them!

Information about the API

Interacting with the API is as simple as using cURL commands with a JSON body. I am writing this as a supplement to what already exists on api.deepgram.com/doc (so check that out for more terse info!).

The top level quantity is your userID. This key is important as it gives access uniquely to your data. You manipulate your account by using the userID to check your balance, submit files for processing (you receive a response with a contentID), check the status of the submitted file, query a specific file, and query a group of files. Some of those actions have properties that can be changed like, 'how do you want your results sorted?', but they also have default values and it's not really necessary to change them for a test.

Account Info

Included you should have in safe keeping a dev key and a starting balance of $20. The key gives you access to the Deepgram API and your starting balance can be used for indexing and searching in your tests. Deductions occur at various rates for indexing and for search (noted below). Further charges may be incurred if utilizing features: full text transcript or keywords, utilizing AI classification techniques like automatic tagging, etc.

  • userID: your-user-id
  • Balance: 40.0 hours free
  • Other rates: contact us for additional features

Test File Info

I used a test file to generate the commands/text you see below. Here are the details of the file:

Note: The above mp3 could be downloaded and listened to for comparison (e.g. by checking that the search results match with the audio in a media player) — it is a ten minute lecture on social epistemology, if you are into that sort of thing.

Also, you can just straight away test with your own files hosted on a server. That way you wouldn't have to bother with the test url. You decide what you need!

Interacting with the Deepgram API

There are several types of interactions that you can have with the API. For instance, you can check your balance, submit audio for processing, check the processing status of a file, query a file, searching through a group of files, and tag a file with metadata. If you have add-on AI services, such as automatic tagging and file classification, then your API endpoint will have other commands.

Check the balance of your account

You can check your account balance very easily with a curl command. In your terminal, do a curl POST with the correct header info to api.deepgram.com like this:

Command:

curl -H "Content-Type: application/json" -X POST -d '{ "action": "get_balance", "userID": "your-user-id" }' api.deepgram.com

Return:

{"balance": 200.0, "userID": "your-user-id"}

Submit Audio for Processing

To submit a file, it must be hosted on a server that is accessible from our API servers. Run the command here with the file URL in place and the file will automatically be downloaded and processed. Right after your submission, the API will return a contentID (keep track of/store that, since it points directly to the file you submitted!).

Command

curl -H "Content-Type: application/json" -X POST -d '{ "action": "index_content", "userID": "your-user-id", "data_url" : "http://www2.warwick.ac.uk/fac/soc/sociology/staff/sfuller/media/audio/9_minutes_on_epistemology.mp3" }' api.deepgram.com

Return

{"contentID": "your-content-id"}

Check the Status of the File

Since it takes ~real time to process the file, you might want to ping the API to check the file's status. This can be done with the command below. When the file is processing, you'll see messages that give the status (like "gen_lattice"), but once the file is finished the command will return a status of 'done'.

Command

curl -H "Content-Type: application/json" -X POST -d '{ "action": "get_object_status", "userID": "your-user-id", "contentID": "your-content-id" }' api.deepgram.com

Return

{"status": "gen_lattice"} < -- you'll get something like this when the file is processing

{"status": "done"} < -- you'll get this once the file is finished and ready to query!

Query a File

Querying the file is as simple as running the below command. There are a few properties that are added in to make the querying function with a good all around behavior (sort by time, get rid of results that don't have a high confidence of being correct, things like that).

Command

This is the code for a search of "social epistemology".

curl -H "Content-Type: application/json" -X POST -d '{ "action": "object_search", "userID": "your-user-id", "contentID": "your-content-id", "query": "social epistemology", "snippet": true, "filter": {"Nmax": 10, "Pmin": 0.55 }, "sort": "time" }' api.deepgram.com

Return

Below is the return for the query "social epistemology".

{"snippet": ["fuller i'm a professor social piz dumas logy at the university", "and wise it important epistemology is the branch", "terms of this issue of the pista mythology has basically been", "of doing business as far as epistemology is concern one"], "P": [0.57404827889915799, 0.69574877064225571, 0.57404827889915799, 0.69574877064225571], "endTime": [4.879999999999999, 14.869999999999997, 188.16000000000005, 382.0199999999999], "startTime": [3.65, 12.657777777777781, 186.97, 380.81], "N": [3, 0, 2, 1]}

Other Actions with the API

There are other actions you can do such as searching through a group of contentIDs or tagging an object with metadata. You can find examples at http://api.deepgram.com/docs that demonstrate the commands and returns. I hope this helps out!