Authenticating

Deepgram's API uses API Keys to authenticate requests. You can view and manage your API Keys in the Deepgram Console or through the Deepgram API.

Your API keys grant many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub or client-side code.

For best results, use different API Keys for testing and production. To help filter usage, you can also use different API Keys for different consumers or teams at your organization.

Before You Begin

Create a Deepgram Account

Before you can use Deepgram products, you'll need to create a Deepgram account. Signup is free and includes:

• $150 in credit, which gives you access to:

  • all base models
  • pre-recorded and streaming functionality
  • all features

Create an API Key

API Keys are associated with Deepgram Projects, which organize all of your Deepgram resources and consist of a set of users, a set of API Keys, and billing and monitoring settings.

When you create an API Key, you assign it a Role, which determines which actions it can be used to perform in the associated Project. Deepgram uses a tiered system of access control to provide granular access to its endpoints. To learn more about roles, see Working with Roles.

Use the Deepgram Console

You must create your first API Key using the Deepgram Console. Thereafter, you can continue to add additional API Keys using the console, or you can create additional API Keys using the Deepgram API.

1. Log in to the Deepgram Console.

2. Locate the Projects dropdown on the top-left, select the project to which you want to add an API Key.

3. Select Settings.

4. Select the API Keys view.

5. Select Create a New API Key.

6. Enter the following settings, and select Create Key:

   Name	Description
   Friendly API Key Name	Name to remember in case you need to retrieve the API Key later using the Deepgram API.
   Role	Role to assign to the API Key. The API Key may perform only the actions allowed by the permissions associated with this role. To learn more about roles, see Working with Roles.

7. Copy the key and save it somewhere safe, then select Got it. For security reasons, we won't be able to show you the key again.

Use the Deepgram API

You must create your first API Key using the Deepgram Console. Thereafter, you can create additional API Keys using the Deepgram API.

Send requests to the API with an Authorization header that references your project's API Key:

Authorization: Token YOUR_DEEPGRAM_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests made without authentication will also fail.

To create additional API Keys using the Deepgram API, run the following in a terminal or your favorite API client:

curl --request POST \
  --url 'https://api.deepgram.com/v1/projects/YOUR_DEEPGRAM_PROJECT_ID/keys' \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"comment":"YOUR_COMMENTS","scopes":["YOUR_ROLES"]}'

Parameters

Configure the code snippet by customizing the placeholder parameters:

Response

A successful request will return a response similar to:

{
  "key": "czyk4m...",
  "api_key_id": "xkhwsk5dr...",
  "comment": "For project members only.",
  "created": "2019-08-24T14:15:22Z",
  "scopes": [
    "member"
  ]
}

Send a Request with the API Key

Once you have created an API Key, you can use it as credentials to call Deepgram's API.

Send requests to the API with an Authorization header that references your project's API Key:

Authorization: Token YOUR_DEEPGRAM_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests made without authentication will also fail.

Transcribe a Remote File

To transcribe audio from a publicly-accessible remote file (for example, hosted in AWS S3 or another server), you would run the following in a terminal or your favorite API client:

curl \
  --request POST \
  --url 'https://api.deepgram.com/v1/listen' \
  --header 'content-type: application/json' \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --data '{"url":"https://static.deepgram.com/examples/interview_speech-analytics.wav"}'

To transcribe from a local file

Transcribe a Local File

To transcribe audio from a file on your computer, run the following in a terminal or your favorite API client:

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @YOUR_AUDIO_WAV \
  --url 'https://api.deepgram.com/v1/listen'

Troubleshoot

To create additional API Keys, be sure that the API Key you are using to authenticate your request has been assigned either the administrator role or the following permissions: keys:read, keys:write.

Make sure you are sending API requests over HTTPS. Calls made over plain HTTP will fail. API requests made without authentication will also fail.