Deepgram JavaScript SDK

Official JavaScript SDK for Deepgram. Power your apps with world-class speech and Language AI models.

• Migrating from v2
• Installation
  • UMD
  • ESM
• Initialization
  • Getting an API Key
• Scoped Configuration
  • Rest requests in the browser
• Transcription (Synchronous)
  • Remote Files
  • Local Files
• Transcription (Asynchronous / Callbacks)
  • Remote Files
  • Local Files
• Transcription (Live / Streaming)
  • Live Audio
• Transcribing to captions
• Projects
  • Get Projects
  • Get Project
  • Update Project
  • Delete Project
• Keys
  • List Keys
  • Get Key
  • Create Key
  • Delete Key
• Members
  • Get Members
  • Remove Member
• Scopes
  • Get Member Scopes
  • Update Scope
• Invitations
  • List Invites
  • Send Invite
  • Delete Invite
  • Leave Project
• Usage
  • Get All Requests
  • Get Request
  • Summarize Usage
  • Get Fields
• Billing
  • Get All Balances
  • Get Balance
• On-Prem APIs
  • List On-Prem credentials
  • Get On-Prem credentials
  • Create On-Prem credentials
  • Delete On-Prem credentials
• Backwards Compatibility
• Development and Contributing
  • Debugging and making changes locally
• Getting Help

Migrating from v2

We have published a migration guide on our docs, showing how to move from v2 to v3.

Installation

You can install this SDK directly from npm.

npm install @deepgram/sdk
# - or -
# yarn add @deepgram/sdk

UMD

You can now use plain <script>s to import deepgram from CDNs, like:

<script src="https://cdn.jsdelivr.net/npm/@deepgram/sdk"></script>

or even:

<script src="https://unpkg.com/@deepgram/sdk"></script>

Then you can use it from a global deepgram variable:

<script>
  const { createClient } = deepgram;
  const _deepgram = createClient("deepgram-api-key");

  console.log("Deepgram Instance: ", _deepgram);
  // ...
</script>

ESM

You can now use type="module" <script>s to import deepgram from CDNs, like:

<script type="module">
  import { createClient } from "https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm";
  const deepgram = createClient("deepgram-api-key");

  console.log("Deepgram Instance: ", deepgram);
  // ...
</script>

Initialization

import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");

const deepgram = createClient(DEEPGRAM_API_KEY);

Getting an API Key

🔑 To access the Deepgram API you will need a free Deepgram API Key.

Scoped Configuration

A new feature is scoped configuration. You'll be able to configure various aspects of the SDK from the initialization.

import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");

const deepgram = createClient(DEEPGRAM_API_KEY, {
  global: { url: "https://api.beta.deepgram.com" },
  // restProxy: { url: "http://localhost:8080" }
});

Rest requests in the browser

This SDK now works in the browser. If you'd like to make REST-based requests (pre-recorded transcription, on-premise, and management requests), then you'll need to use a proxy as we do not support custom CORS origins on our API. To set up your proxy, you configure the SDK like so:

import { createClient } from "@deepgram/sdk";

const deepgram = createClient("proxy", {
  restProxy: { url: "http://localhost:8080" },
});

Important: You must pass "proxy" as your API key, and use the proxy to set the Authorization header to your Deepgram API key.

Your proxy service should replace the Authorization header with Authorization: token <DEEPGRAM_API_KEY> and return results verbatim to the SDK.

Check out our example Node-based proxy here: Deepgram Node Proxy.

Transcription (Synchronous)

Remote Files

const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  {
    model: "nova",
  }
);

See our API reference for more info.

Local Files

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  fs.createReadStream("./examples/spacewalk.wav"),
  {
    model: "nova",
  }
);

or

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  fs.readFileSync("./examples/spacewalk.wav"),
  {
    model: "nova",
  }
);

See our API reference for more info.

Transcription (Asynchronous / Callbacks)

Remote Files

import { CallbackUrl } from "@deepgram/sdk";

const { result, error } = await deepgram.listen.prerecorded.transcribeUrlCallback(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova",
  }
);

See our API reference for more info.

Local Files

import { CallbackUrl } from "@deepgram/sdk";

const { result, error } = await deepgram.listen.prerecorded.transcribeFileCallback(
  fs.createReadStream("./examples/spacewalk.wav"),
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova",
  }
);

or

import { CallbackUrl } from "@deepgram/sdk";

const { result, error } = await deepgram.listen.prerecorded.transcribeFileCallback(
  fs.readFileSync("./examples/spacewalk.wav"),
  new CallbackUrl("http://callback/endpoint"),
  {
    model: "nova",
  }
);

See our API reference for more info.

Transcription (Live / Streaming)

Live Audio

const dgConnection = deepgram.listen.live({ model: "nova" });

dgConnection.on(LiveTranscriptionEvents.Open, () => {
  dgConnection.on(LiveTranscriptionEvents.Transcript, (data) => {
    console.log(data);
  });

  source.addListener("got-some-audio", async (event) => {
    dgConnection.send(event.raw_audio_data);
  });
});

To see an example, check out our Node.js example or our Browser example.

See our API reference for more info.

Transcribing to captions

import { webvtt /* , srt */ } from "@deepgram/captions";

const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  {
    model: "nova",
  }
);

const vttOutput = webvtt(result);
// const srtOutput = srt(result);

See our standalone captions library for more information.

Projects

Get Projects

Returns all projects accessible by the API key.

const { result, error } = await deepgram.manage.getProjects();

See our API reference for more info.

Get Project

Retrieves a specific project based on the provided project_id.

const { result, error } = await deepgram.manage.getProject(projectId);

See our API reference for more info.

Update Project

Update a project.

const { result, error } = await deepgram.manage.updateProject(projectId, options);

See our API reference for more info.

Delete Project

Delete a project.

const { error } = await deepgram.manage.deleteProject(projectId);

See our API reference for more info.

Keys

List Keys

Retrieves all keys associated with the provided project_id.

const { result, error } = await deepgram.manage.getProjectKeys(projectId);

See our API reference for more info.

Get Key

Retrieves a specific key associated with the provided project_id.

const { result, error } = await deepgram.manage.getProjectKey(projectId, projectKeyId);

See our API reference for more info.

Create Key

Creates an API key with the provided scopes.

const { result, error } = await deepgram.manage.createProjectKey(projectId, options);

See our API reference for more info.

Delete Key

Deletes a specific key associated with the provided project_id.

const { error } = await deepgram.manage.deleteProjectKey(projectId, projectKeyId);

See our API reference for more info.

Members

Get Members

Retrieves account objects for all of the accounts in the specified project_id.

const { result, error } = await deepgram.manage.getProjectMembers(projectId);

See our API reference for more info.

Remove Member

Removes member account for specified member_id.

const { error } = await deepgram.manage.removeProjectMember(projectId, projectMemberId);

See our API reference for more info.

Scopes

Get Member Scopes

Retrieves scopes of the specified member in the specified project.

const { result, error } = await deepgram.manage.getProjectMemberScopes(projectId, projectMemberId);

See our API reference for more info.

Update Scope

Updates the scope for the specified member in the specified project.

const { result, error } = await deepgram.manage.updateProjectMemberScope(
  projectId,
  projectMemberId,
  options
);

See our API reference for more info.

Invitations

List Invites

Retrieves all invitations associated with the provided project_id.

const { result, error } = await deepgram.manage.getProjectInvites(projectId);

See our API reference for more info.

Send Invite

Sends an invitation to the provided email address.

const { result, error } = await deepgram.manage.sendProjectInvite(projectId, options);

See our API reference for more info.

Delete Invite

Removes the specified invitation from the project.

const { error } = await deepgram.manage.deleteProjectInvite(projectId, email);

See our API reference for more info.

Leave Project

Removes the authenticated user from the project.

const { result, error } = await deepgram.manage.leaveProject(projectId);

See our API reference for more info.

Usage

Get All Requests

Retrieves all requests associated with the provided project_id based on the provided options.

const { result, error } = await deepgram.manage.getProjectUsageRequest(projectId, requestId);

See our API reference for more info.

Get Request

Retrieves a specific request associated with the provided project_id.

const { result, error } = await deepgram.manage.getProjectUsageRequest(projectId, requestId);

See our API reference for more info.

Summarize Usage

Retrieves usage associated with the provided project_id based on the provided options.

const { result, error } = await deepgram.manage.getProjectUsageSummary(projectId, options);

See our API reference for more info.

Get Fields

Lists the features, models, tags, languages, and processing method used for requests in the specified project.

const { result, error } = await deepgram.manage.getProjectUsageFields(projectId, options);

See our API reference for more info.

Billing

Get All Balances

Retrieves the list of balance info for the specified project.

const { result, error } = await deepgram.manage.getProjectBalances(projectId);

See our API reference for more info.

Get Balance

Retrieves the balance info for the specified project and balance_id.

const { result, error } = await deepgram.manage.getProjectBalance(projectId, balanceId);

See our API reference for more info.

On-Prem APIs

List On-Prem credentials

const { result, error } = await deepgram.onprem.listCredentials(projectId);

Get On-Prem credentials

const { result, error } = await deepgram.onprem.getCredentials(projectId, credentialId);

Create On-Prem credentials

const { result, error } = await deepgram.onprem.createCredentials(projectId, options);

Delete On-Prem credentials

const { result, error } = await deepgram.onprem.deleteCredentials(projectId, credentialId);

Backwards Compatibility

Older SDK versions will receive Priority 1 (P1) bug support only. Security issues, both in our code and dependencies, are promptly addressed. Significant bugs without clear workarounds are also given priority attention.

Development and Contributing

Interested in contributing? We ❤️ pull requests!

To make sure our community is safe for all, be sure to review and agree to our Code of Conduct. Then see the Contribution guidelines for more information.

Debugging and making changes locally

If you want to make local changes to the SDK and run the examples/, you'll need to npm run build first, to ensure that your changes are included in the examples that are running.

Getting Help

We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:

• Open an issue in this repository
• Join the Deepgram Discord Community
• Join the Deepgram Github Discussions Community