Deepgram API TypeScript Library

Power your apps with world-class speech and Language AI models

Documentation

API reference documentation is available here.

Migrating from earlier versions

V2 to V3

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

V3.* to V3.4

We recommend using only documented interfaces, as we strictly follow semantic versioning (semver) and breaking changes may occur for undocumented interfaces. To ensure compatibility, consider pinning your versions if you need to use undocumented interfaces.

V3.* to V4

The Voice Agent interfaces have been updated to use the new Voice Agent V1 API. Please refer to our Documentation on Migration to new V1 Agent API.

V4 to V5

The SDK has been rebuilt using Fern for auto-generation, providing better TypeScript support and a more structured API. See MIGRATION_GUIDE_V4_TO_V5.md for a comprehensive migration guide.

Key breaking changes:

• Client initialization: createClient() → new DeepgramClient()
• Options property: key → apiKey
• API methods now include version namespaces (e.g., listen.v1.media.transcribeUrl())
• Error handling: Use try/catch instead of { result, error } pattern

Installation

npm i -s @deepgram/sdk

Authentication

The Deepgram SDK supports three authentication methods:

1. API Key Authentication (Recommended)

Uses Token scheme in Authorization header.

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

// Method 1: Pass API key in options object
const deepgramClient = new DeepgramClient({ apiKey: "YOUR_DEEPGRAM_API_KEY" });

// Method 2: Use environment variable (DEEPGRAM_API_KEY)
const deepgramClient = new DeepgramClient();

2. Access Token Authentication

Uses Bearer scheme in Authorization header. Access tokens are temporary (30-second TTL) and must be obtained using an API key.

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

// Pass access token as apiKey property
const deepgramClient = new DeepgramClient({ accessToken: "YOUR_ACCESS_TOKEN" });

// Or use environment variable (DEEPGRAM_ACCESS_TOKEN)
const deepgramClient = new DeepgramClient();

3. Proxy Authentication

For browser environments or custom proxy setups. Pass "proxy" as the API key.

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

const deepgramClient = new DeepgramClient({
  apiKey: "proxy",
  baseUrl: "http://localhost:8080"
});

Important: Your proxy must set the Authorization: token DEEPGRAM_API_KEY header and forward requests to Deepgram's API.

Getting Credentials

API Keys

Create API keys via the Management API:

const data = await deepgramClient.manage.v1.keys.create(projectId, {
  comment: "My API key",
  scopes: ["usage:write"],
});

Endpoint: POST https://api.deepgram.com/v1/projects/:projectId/keys

Access Tokens

Generate temporary access tokens (requires existing API key):

const data = await deepgramClient.auth.v1.tokens.grant();
// Returns: { access_token: string, expires_in: 30 }

Endpoint: POST https://api.deepgram.com/v1/auth/grant

Environment Variables

The SDK automatically checks for credentials in this priority order:

1. DEEPGRAM_ACCESS_TOKEN (highest priority)
2. DEEPGRAM_API_KEY (fallback)

Getting an API Key

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

Scoped Configuration

The SDK supports scoped configuration. You'll be able to configure various aspects of each namespace of the SDK from the initialization. Below outlines a flexible and customizable configuration system for the Deepgram SDK. Here's how the namespace configuration works:

Global Defaults

• The global namespace serves as the foundational configuration applicable across all other namespaces unless overridden.
• Includes general settings like URL and headers applicable for all API calls.
• If no specific configurations are provided for other namespaces, the global defaults are used.

Namespace-specific Configurations

• Each namespace (listen, manage, onprem, read, speak) can have its specific configurations which override the global settings within their respective scopes.
• Allows for detailed control over different parts of the application interacting with various Deepgram API endpoints.

Transport Options

• Configurations for both fetch and websocket can be specified under each namespace, allowing different transport mechanisms for different operations.
• For example, the fetch configuration can have its own URL and proxy settings distinct from the websocket.
• The generic interfaces define a structure for transport options which include a client (like a fetch or WebSocket instance) and associated options (like headers, URL, proxy settings).

This configuration system enables robust customization where defaults provide a foundation, but every aspect of the client's interaction with the API can be finely controlled and tailored to specific needs through namespace-specific settings. This enhances the maintainability and scalability of the application by localizing configurations to their relevant contexts.

Examples

Change the API url used for all SDK methods

Useful for using different API environments (for e.g. beta).

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

const deepgramClient = new DeepgramClient({
  apiKey: DEEPGRAM_API_KEY,
  baseUrl: "https://api.beta.deepgram.com"
});

Change the API url used for the Voice Agent websocket

Useful for using a voice agent proxy (for e.g. 3rd party provider auth).

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

const deepgramClient = new DeepgramClient({
  apiKey: DEEPGRAM_API_KEY,
  baseUrl: "ws://localhost:8080"
});

Change the API url used for transcription only

Useful for on-prem installations. Only affects requests to /listen endpoints.

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

const deepgramClient = new DeepgramClient({
  apiKey: DEEPGRAM_API_KEY,
  baseUrl: "http://localhost:8080"
});

Override fetch transmitter

Useful for providing a custom http client.

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

const yourFetch = async () => {
  return Response("...etc");
};

const deepgramClient = new DeepgramClient({
  apiKey: DEEPGRAM_API_KEY,
  fetch: yourFetch
});

Proxy requests in the browser (Required)

Due to CORS header restrictions in the Deepgram API, you must use a proxy server when making REST API calls from browsers. To set up your proxy, you configure the SDK like so:

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

const deepgramClient = new DeepgramClient({
  apiKey: "proxy",
  baseUrl: "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.

Why is a proxy required? The SDK sends custom headers (X-Fern-Runtime-Version, etc.) that are not whitelisted by the Deepgram API's CORS configuration, causing preflight requests to fail. A proxy bypasses this limitation while also keeping your API key secure.

Set custom headers for fetch

Useful for many things.

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

const deepgramClient = new DeepgramClient({
  apiKey: "YOUR_API_KEY",
  headers: { "x-custom-header": "foo" }
});

Browser Usage

The SDK works in modern browsers with some considerations:

WebSocket Features (Full Support)

• Live Transcription: ✅ Direct connection to wss://api.deepgram.com
• Voice Agent: ✅ Direct connection to wss://agent.deepgram.com
• Live Text-to-Speech: ✅ Direct connection to wss://api.deepgram.com

REST API Features (Proxy Required)

• Pre-recorded Transcription: ⚠️ Requires proxy due to CORS header restrictions
• Text Intelligence: ⚠️ Requires proxy due to CORS header restrictions
• Management APIs: ⚠️ Requires proxy due to CORS header restrictions

Important: The SDK sends custom headers that are not allowed by the Deepgram API's CORS policy. You must use a proxy server (see setup instructions above) to make REST API calls from browsers.

Setup Options

Option 1: CDN (UMD)

<script src="https://cdn.jsdelivr.net/npm/@deepgram/sdk"></script>
<script>
  const { DeepgramClient } = deepgram;
  const deepgramClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
</script>

Option 2: CDN (ESM)

<script type="module">
  import { DeepgramClient } from "https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm";
  const deepgramClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
</script>

Option 3: NPM Package (Browser Bundle)

After installing via npm install @deepgram/sdk, you can use the browser bundle:

Method A: Copy the bundle to your public directory

# Copy the browser bundle to your static assets folder
cp node_modules/@deepgram/sdk/dist/browser/index.global.js public/deepgram.js

Then include it in your HTML:

<script src="/deepgram.js"></script>
<script>
  const { DeepgramClient } = Deepgram;
  const deepgramClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
</script>

Method B: Reference directly from node_modules (development only)

If your dev server serves files from node_modules, you can reference it directly:

<script src="/node_modules/@deepgram/sdk/dist/browser/index.global.js"></script>
<script>
  const { DeepgramClient } = Deepgram;
  const deepgramClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
</script>

Method C: Use a bundler (Webpack, Vite, etc.)

Import the SDK in your JavaScript/TypeScript code and let your bundler handle it:

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

const deepgramClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });

Option 4: Proxy for REST APIs

See proxy requests in the browser to hide your API key from client-side code.

Transcription

Remote Files

Transcribe audio from a URL.

const data = await deepgramClient.listen.v1.media.transcribeUrl({
  url: "https://dpgr.am/spacewalk.wav",
  model: "nova-3",
  // pre-recorded transcription options
});

API Endpoint: POST https://api.deepgram.com/v1/listen

See our API reference for more info.

Local Files

Transcribe audio from a file.

const data = await deepgramClient.listen.v1.media.transcribeFile(
  fs.createReadStream("./examples/spacewalk.wav"),
  {
    model: "nova-3",
    // pre-recorded transcription options
  }
);

API Endpoint: POST https://api.deepgram.com/v1/listen

See our API reference for more info.

Callbacks / Async

Transcribe with a callback URL for async processing.

const data = await deepgramClient.listen.v1.media.transcribeUrl({
  url: "https://dpgr.am/spacewalk.wav",
  callback: "http://callback/endpoint",
  callback_method: "POST",
  model: "nova-3",
  // pre-recorded transcription options
});

API Endpoint: POST https://api.deepgram.com/v1/listen?callback=http://callback/endpoint

See our API reference for more info.

Live Transcription (WebSocket)

Connect to our websocket and transcribe live streaming audio.

const deepgramConnection = await deepgramClient.listen.v1.connect({
  model: "nova-3",
  language: "en",
  punctuate: "true",
  interim_results: "true",
  // live transcription options
});

deepgramConnection.on("open", () => {
  console.log("Connection opened");
});

deepgramConnection.on("message", (data) => {
  if (data.type === "Results") {
    console.log(data);
  }
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

// Send audio data
source.addListener("got-some-audio", async (event) => {
  deepgramConnection.socket.send(event.raw_audio_data);
});

WebSocket Endpoint: wss://api.deepgram.com/v1/listen

See our API reference for more info.

Captions

Convert deepgram transcriptions to captions.

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

const data = await deepgramClient.listen.v1.media.transcribeUrl({
  url: "https://dpgr.am/spacewalk.wav",
  model: "nova-3",
  // pre-recorded transcription options
});

const vttResult = webvtt(data);
const srtResult = srt(data);

See our standalone captions library for more information.

Voice Agent

Configure a Voice Agent.

// Create an agent connection
const deepgramConnection = await deepgramClient.agent.v1.connect();

// Set up event handlers
deepgramConnection.on("open", () => {
  console.log("Connection opened");
});

deepgramConnection.on("message", (data) => {
  if (data.type === "ConversationText") {
    console.log(data);
  }
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

// Configure the agent once connection is established
deepgramConnection.sendAgentV1Settings({
  type: "Settings",
  agent: {
    language: "en",
    listen: {
      provider: {
        type: "deepgram",
        model: "nova-3"
      }
    },
    think: {
      provider: {
        type: "open_ai",
        model: "gpt-4o-mini"
      },
      prompt: "You are a friendly AI assistant."
    },
    speak: {
      provider: {
        type: "deepgram",
        model: "aura-2-thalia-en"
      }
    }
  }
});

WebSocket Endpoint: wss://agent.deepgram.com/v1/agent/converse

See our API reference for more info.

Text to Speech

Single-Request

Convert text into speech using the REST API.

const data = await deepgramClient.speak.v1.audio.generate({
  text: "Hello, world!",
  model: "aura-2-thalia-en",
  encoding: "linear16",
  container: "wav",
  // text to speech options
});

API Endpoint: POST https://api.deepgram.com/v1/speak

See our API reference for more info.

Continuous Text Stream (WebSocket)

Connect to our websocket and send a continuous text stream to generate speech.

const deepgramConnection = await deepgramClient.speak.v1.connect({
  model: "aura-2-thalia-en",
  encoding: "linear16",
  sample_rate: 24000,
  // live text to speech options
});

deepgramConnection.on("open", () => {
  console.log("Connection opened");
});

deepgramConnection.on("message", (data) => {
  if (typeof data === "string") {
    // Audio data as base64 string
    const audioBuffer = Buffer.from(data, "base64");
    // Handle audio
  }
});

deepgramConnection.on("close", () => {
  console.log("Connection closed");
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

// Send text data for TTS synthesis
deepgramConnection.sendSpeakV1Text({ type: "Text", text: "Hello, world!" });

WebSocket Endpoint: wss://api.deepgram.com/v1/speak

See our API reference for more info.

Text Intelligence

Analyze text using our intelligence AI features.

const text = `The history of the phrase 'The quick brown fox jumps over the
lazy dog'. The earliest known appearance of the phrase was in The Boston
Journal...`;

const data = await deepgramClient.read.v1.text.analyze({
  text,
  language: "en",
  // text intelligence options
});

API Endpoint: POST https://api.deepgram.com/v1/read

See our API reference for more info.

Token Management

Get Token Details

Retrieves the details of the current authentication token.

const data = await deepgramClient.auth.v1.tokens.get();

API Endpoint: GET https://api.deepgram.com/v1/auth/token

See our API reference for more info

Grant Access Token

Creates a temporary access token with a 30-second TTL. Requires an existing API key for authentication.

// Create a temporary access token
const data = await deepgramClient.auth.v1.tokens.grant();
// Returns: { access_token: string, expires_in: 30 }

// Use the access token in a new client instance
const tempClient = new DeepgramClient({ apiKey: data.access_token });

API Endpoint: POST https://api.deepgram.com/v1/auth/grant

Important: You must pass an accessToken property to use a temporary token. Passing the token as a raw string will treat it as an API key and use the incorrect authorization scheme.

See our API reference for more info.

Projects

Get Projects

Returns all projects accessible by the API key.

const data = await deepgramClient.manage.v1.projects.list();

API Endpoint: GET https://api.deepgram.com/v1/projects

See our API reference for more info.

Get Project

Retrieves a specific project based on the provided project_id.

const data = await deepgramClient.manage.v1.projects.get(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId

See our API reference for more info.

Update Project

Update a project.

const data = await deepgramClient.manage.v1.projects.update(projectId, {
  name: "Updated Project Name"
});

API Endpoint: PATCH https://api.deepgram.com/v1/projects/:projectId

See our API reference for more info.

Delete Project

Delete a project.

await deepgramClient.manage.v1.projects.delete(projectId);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId

See our API reference for more info.

Keys

List Keys

Retrieves all keys associated with the provided project_id.

const data = await deepgramClient.manage.v1.keys.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/keys

See our API reference for more info.

Get Key

Retrieves a specific key associated with the provided project_id.

const data = await deepgramClient.manage.v1.keys.get(projectId, projectKeyId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/keys/:keyId

See our API reference for more info.

Create Key

Creates an API key with the provided scopes.

const data = await deepgramClient.manage.v1.keys.create(projectId, {
  comment: "My API key",
  scopes: ["usage:write"], // Required: array of scope strings
  tags: ["production"], // Optional: array of tag strings
  time_to_live_in_seconds: 86400, // Optional: TTL in seconds
  // OR use expiration_date: "2024-12-31T23:59:59Z" // Optional: ISO date string
});

API Endpoint: POST https://api.deepgram.com/v1/projects/:projectId/keys

See our API reference for more info.

Delete Key

Deletes a specific key associated with the provided project_id.

await deepgramClient.manage.v1.keys.delete(projectId, projectKeyId);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId/keys/:keyId

See our API reference for more info.

Members

Get Members

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

const data = await deepgramClient.manage.v1.members.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/members

See our API reference for more info.

Remove Member

Removes member account for specified member_id.

await deepgramClient.manage.v1.members.delete(projectId, projectMemberId);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId/members/:memberId

See our API reference for more info.

Scopes

Get Member Scopes

Retrieves scopes of the specified member in the specified project.

const data = await deepgramClient.manage.v1.members.scopes.get(
  projectId,
  projectMemberId
);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/members/:memberId/scopes

See our API reference for more info.

Update Scope

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

const data = await deepgramClient.manage.v1.members.scopes.update(
  projectId,
  projectMemberId,
  {
    scopes: ["usage:write", "usage:read"]
  }
);

API Endpoint: PUT https://api.deepgram.com/v1/projects/:projectId/members/:memberId/scopes

See our API reference for more info.

Invitations

List Invites

Retrieves all invitations associated with the provided project_id.

const data = await deepgramClient.manage.v1.invites.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/invites

See our API reference for more info.

Send Invite

Sends an invitation to the provided email address.

const data = await deepgramClient.manage.v1.invites.create(projectId, {
  email: "user@example.com",
  scope: "member"
});

API Endpoint: POST https://api.deepgram.com/v1/projects/:projectId/invites

See our API reference for more info.

Delete Invite

Removes the specified invitation from the project.

await deepgramClient.manage.v1.invites.delete(projectId, email);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId/invites/:email

See our API reference for more info.

Leave Project

Removes the authenticated user from the project.

await deepgramClient.manage.v1.invites.leave(projectId);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId/leave

See our API reference for more info.

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

import { createReadStream } from "fs";
import { DeepgramClient } from "@deepgram/sdk";

const client = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
await client.listen.v1.media.transcribeFile(createReadStream("path/to/file"), {});

Billing

Get All Balances

Retrieves the list of balance info for the specified project.

const data = await deepgramClient.manage.v1.billing.balances.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/balances

See our API reference for more info.

Get Balance

Retrieves the balance info for the specified project and balance_id.

const data = await deepgramClient.manage.v1.billing.balances.get(projectId, balanceId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/balances/:balanceId

See our API reference for more info.

Models

Get All Models

Retrieves all models available globally.

const data = await deepgramClient.manage.v1.models.list();

API Endpoint: GET https://api.deepgram.com/v1/models

Get All Project Models

Retrieves all models available for a given project.

const data = await deepgramClient.manage.v1.models.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/models

See our API reference for more info.

Get Model

Retrieves details of a specific model.

const data = await deepgramClient.manage.v1.models.get(projectId, modelId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/models/:modelId

See our API reference for more info

On-Prem APIs

List On-Prem credentials

Lists sets of distribution credentials for the specified project.

const data = await deepgramClient.selfHosted.v1.distributionCredentials.list(projectId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/onprem/distribution/credentials

See our API reference for more info

Get On-Prem credentials

Returns a set of distribution credentials for the specified project.

const data = await deepgramClient.selfHosted.v1.distributionCredentials.get(projectId, credentialId);

API Endpoint: GET https://api.deepgram.com/v1/projects/:projectId/onprem/distribution/credentials/:credentialsId

See our API reference for more info

Create On-Prem credentials

Creates a set of distribution credentials for the specified project.

const data = await deepgramClient.selfHosted.v1.distributionCredentials.create(projectId, {
  comment: "Production credentials"
});

API Endpoint: POST https://api.deepgram.com/v1/projects/:projectId/onprem/distribution/credentials

See our API reference for more info

Delete On-Prem credentials

Deletes a set of distribution credentials for the specified project.

await deepgramClient.selfHosted.v1.distributionCredentials.delete(projectId, credentialId);

API Endpoint: DELETE https://api.deepgram.com/v1/projects/:projectId/onprem/distribution/credentials/:credentialsId

See our API reference for more info

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 pnpm 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

Request And Response Types

The SDK exports all request and response types as TypeScript interfaces. You can import them in two ways:

Direct Import (Recommended)

Import types directly for better IDE autocomplete and discoverability:

import {
  ListenV1Response,
  SpeakV1Response,
  ReadV1Response,
  GetProjectV1Response,
  CreateKeyV1Response,
  UsageV1Response,
} from "@deepgram/sdk";

// Use types directly
async function handleTranscription(response: ListenV1Response) {
  console.log(response.metadata);
  console.log(response.results);
}

async function handleProject(project: GetProjectV1Response) {
  console.log(project.projectId);
  console.log(project.name);
}

Namespace Import

Alternatively, import types via the Deepgram namespace:

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

// Use types via namespace
async function handleTranscription(response: Deepgram.ListenV1Response) {
  console.log(response.metadata);
  console.log(response.results);
}

const request: Deepgram.GrantV1Request = {
  // ...
};

Both import styles refer to the same types and can be used interchangeably or mixed in the same file.

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

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

try {
    await client.listen.v1.media.transcribeFile(...);
} catch (err) {
    if (err instanceof DeepgramError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
        console.log(err.rawResponse);
    }
}

File Uploads

You can upload files using the client:

import { createReadStream } from "fs";

await client.listen.v1.media.transcribeFile(createReadStream("path/to/file"), ...);
await client.listen.v1.media.transcribeFile(new ReadableStream(), ...);
await client.listen.v1.media.transcribeFile(Buffer.from('binary data'), ...);
await client.listen.v1.media.transcribeFile(new Blob(['binary data'], { type: 'audio/mpeg' }), ...);
await client.listen.v1.media.transcribeFile(new File(['binary data'], 'file.mp3'), ...);
await client.listen.v1.media.transcribeFile(new ArrayBuffer(8), ...);
await client.listen.v1.media.transcribeFile(new Uint8Array([0, 1, 2]), ...);

The client accepts a variety of types for file upload parameters:

• Stream types: fs.ReadStream, stream.Readable, and ReadableStream
• Buffered types: Buffer, Blob, File, ArrayBuffer, ArrayBufferView, and Uint8Array

Metadata

You can configure metadata when uploading a file:

const file: Uploadable.WithMetadata = {
    data: createReadStream("path/to/file"),
    filename: "my-file",       // optional
    contentType: "audio/mpeg", // optional
    contentLength: 1949,       // optional
};

Alternatively, you can upload a file directly from a file path:

const file : Uploadable.FromPath = {
    path: "path/to/file",
    filename: "my-file",        // optional
    contentType: "audio/mpeg",  // optional
    contentLength: 1949,        // optional
};

The metadata is used to set the Content-Length, Content-Type, and Content-Disposition headers. If not provided, the client will attempt to determine them automatically. For example, fs.ReadStream has a path property which the SDK uses to retrieve the file size from the filesystem without loading it into memory.

Binary Response

You can consume binary data from endpoints using the BinaryResponse type which lets you choose how to consume the data:

const response = await client.speak.v1.audio.generate(...);
const stream: ReadableStream<Uint8Array> = response.stream();
// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
// const blob: Blob = response.blob();
// const bytes: Uint8Array = response.bytes();
// You can only use the response body once, so you must choose one of the above methods.
// If you want to check if the response body has been used, you can use the following property.
const bodyUsed = response.bodyUsed;

Advanced

Additional Headers

If you would like to send additional headers as part of the request, use the headers request option.

const response = await client.listen.v1.media.transcribeFile(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});

Additional Query String Parameters

If you would like to send additional query string parameters as part of the request, use the queryParams request option.

const response = await client.listen.v1.media.transcribeFile(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await client.listen.v1.media.transcribeFile(..., {
    maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.

const response = await client.listen.v1.media.transcribeFile(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

const controller = new AbortController();
const response = await client.listen.v1.media.transcribeFile(..., {
    abortSignal: controller.signal
});
controller.abort(); // aborts the request

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .withRawResponse() method. The .withRawResponse() method returns a promise that results to an object with a data and a rawResponse property.

const { data, rawResponse } = await client.listen.v1.media.transcribeFile(...).withRawResponse();

console.log(data);
console.log(rawResponse.headers['X-My-Header']);

Logging

The SDK supports logging. You can configure the logger by passing in a logging object to the client options.

import { DeepgramClient, logging } from "@deepgram/sdk";

const client = new DeepgramClient({
    ...
    logging: {
        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
        silent: false, // defaults to true, set to false to enable logging
    }
});

The logging object can have the following properties:

• level: The log level to use. Defaults to logging.LogLevel.Info.
• logger: The logger to use. Defaults to a logging.ConsoleLogger.
• silent: Whether to silence the logger. Defaults to true.

The level property can be one of the following values:

• logging.LogLevel.Debug
• logging.LogLevel.Info
• logging.LogLevel.Warn
• logging.LogLevel.Error

To provide a custom logger, you can pass in an object that implements the logging.ILogger interface.

import winston from 'winston';

const winstonLogger = winston.createLogger({...});

const logger: logging.ILogger = {
    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
    info: (msg, ...args) => winstonLogger.info(msg, ...args),
    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
    error: (msg, ...args) => winstonLogger.error(msg, ...args),
};

import pino from 'pino';

const pinoLogger = pino({...});

const logger: logging.ILogger = {
  debug: (msg, ...args) => pinoLogger.debug(args, msg),
  info: (msg, ...args) => pinoLogger.info(args, msg),
  warn: (msg, ...args) => pinoLogger.warn(args, msg),
  error: (msg, ...args) => pinoLogger.error(args, msg),
};

Runtime Compatibility

The SDK works in the following runtimes:

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Customizing Fetch Client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break glass and ensure the SDK works.

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

const client = new DeepgramClient({
    ...
    fetcher: // provide your implementation here
});

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!