Required dependencies

npm install ws
npm install --save-dev @types/ws

No native build steps, pod installs, or Android linking are required. This is a pure Node.js/TypeScript package.

Project setup

1. Copy the source/ directory into your project, e.g. src/deepgram/.

2. Add path aliases in tsconfig.json so your code resolves the source root cleanly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@deepgram/sdk": ["src/deepgram/index.ts"]
    },
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020",
    "esModuleInterop": true
  }
}

3. If you use a bundler (esbuild, Webpack, tsup), add the same alias there. For tsup:

// tsup.config.ts
export default { alias: { "@deepgram/sdk": "./src/deepgram/index.ts" } };

4. Set the required environment variable before running:

export DEEPGRAM_API_KEY="your_api_key_here"

5. The SDK reads process.env.DEEPGRAM_API_KEY automatically. You can also pass it explicitly to the constructor (see examples below).

Public API

DeepgramClient

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

const client = new DeepgramClient(options?: BaseClientOptions);

The main entry point for all SDK functionality. BaseClientOptions accepts apiKey, global, and namespace fields. Use this class when you need a custom auth flow or want to inject additional headers. This is CustomDeepgramClient under the hood.

DefaultDeepgramClient

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

const client = new DefaultDeepgramClient(options?: BaseClientOptions);

The upstream SDK's canonical client class. Use when you want the out-of-the-box Deepgram-hosted endpoint configuration without customization. Exposes .listen, .speak, .read, .agent, .manage, .auth, .selfHosted, and .voiceAgent resource namespaces.

DeepgramEnvironment

import { DeepgramEnvironment, type DeepgramEnvironmentUrls } from "@deepgram/sdk";

// Values: DeepgramEnvironment.Default, DeepgramEnvironment.SelfHosted, etc.

Enum for selecting the API base URL. Pass environment: DeepgramEnvironment.Default in BaseClientOptions to explicitly target Deepgram's cloud, or provide a DeepgramEnvironmentUrls object to point at a self-hosted deployment.

DeepgramError / DeepgramTimeoutError

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

Base error classes for all SDK failures. Catch DeepgramError for API-level problems and DeepgramTimeoutError for requests that exceeded their deadline. Both are subclasses of Error and carry a structured message.

Working examples

Scenario - Pre-recorded file transcription

Send a local audio file to Deepgram's speech-to-text API and print the transcript. The listen.v1.media.transcribeFile method accepts a ReadStream and a model options object.

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

async function transcribeFile(filePath: string): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const response = await client.listen.v1.media.transcribeFile(
    createReadStream(filePath),
    { model: "nova-3", punctuate: true, language: "en" }
  );

  const transcript =
    response.results.channels[0].alternatives[0].transcript;
  console.log("Transcript:", transcript);
}

transcribeFile("./audio.wav");

Scenario - Real-time streaming transcription

Open a WebSocket to Deepgram and stream raw PCM audio chunks as they arrive from a microphone or other audio source.

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

async function streamAudio(audioChunks: AsyncIterable<Buffer>): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const connection = await client.listen.v1.connect({
    model: "nova-3",
    language: "en",
    punctuate: "true",
    interim_results: "true",
  });

  connection.on("open", () => console.log("WebSocket open"));

  connection.on("message", (data: unknown) => {
    const msg = data as { type: string; channel?: { alternatives: { transcript: string }[] } };
    if (msg.type === "Results") {
      console.log(msg.channel?.alternatives[0].transcript);
    }
  });

  connection.on("error", (err: Error) => {
    if (err instanceof DeepgramError) {
      console.error("Deepgram error:", err.message);
    }
  });

  connection.connect();
  await connection.waitForOpen();

  for await (const chunk of audioChunks) {
    connection.socket.send(chunk);
  }

  connection.socket.close();
}

Scenario - Text-to-speech audio generation

Convert a string of text into a WAV audio stream using Deepgram's TTS API and pipe it to a file.

import { createWriteStream } from "fs";
import { pipeline } from "stream/promises";
import { DeepgramClient } from "@deepgram/sdk";

async function synthesizeSpeech(text: string, outPath: string): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const response = await client.speak.v1.audio.generate({
    text,
    model: "aura-2-thalia-en",
    encoding: "linear16",
    container: "wav",
  });

  const audioStream = response.stream();
  const fileWriter = createWriteStream(outPath);
  await pipeline(audioStream, fileWriter);
  console.log("Audio saved to", outPath);
}

synthesizeSpeech("Hello from Deepgram.", "./output.wav");

Scenario - Voice agent over WebSocket

Establish a conversational voice agent session, configure it with a LLM provider, and handle agent responses.

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

async function runVoiceAgent(): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const connection = await client.agent.v1.connect();

  connection.on("open", () => {
    connection.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 concise AI assistant.",
        },
        speak: { provider: { type: "deepgram", model: "aura-2-thalia-en" } },
      },
    });
  });

  connection.on("message", (data: { type: string; role?: string; content?: string }) => {
    if (data.type === "ConversationText") {
      console.log(`[${data.role}]:`, data.content);
    }
  });

  connection.connect();
  await connection.waitForOpen();
}

runVoiceAgent();

File walkthrough

• index.ts - Root barrel; exports the Deepgram namespace alias plus all types and resource classes as named exports.
• Client.ts - Defines DeepgramClient (the upstream default client); wires together all resource sub-clients against Deepgram's hosted endpoints.
• CustomClient.ts - CustomDeepgramClient (re-exported as DeepgramClient); allows overriding HTTP transport and auth headers.
• BaseClient.ts - Abstract base with BaseClientOptions and BaseRequestOptions; inherited by both client variants.
• environments.ts - DeepgramEnvironment enum and DeepgramEnvironmentUrls type controlling which base URLs the SDK calls.
• errors/ - DeepgramError and DeepgramTimeoutError; all SDK-thrown errors extend these.
• exports.ts - Supplementary re-exports bundled by the SDK build pipeline.
• version.ts - Exports the SDK semver string; useful for logging and support diagnostics.
• api/ - Top-level namespace for all API resources, errors, and shared types.
• api/errors/ - BadRequestError (HTTP 400 wrapper) and other HTTP-status error classes.
• api/resources/agent/ - Voice agent client and WebSocket socket wrapper for conversational AI.
• api/resources/listen/ - Streaming and pre-recorded speech-to-text clients.
• api/resources/speak/ - Text-to-speech REST client.
• api/resources/read/ - Text analysis client (sentiment, topics, intents).
• api/resources/manage/ - Project, key, and member management REST clients.
• api/resources/auth/ - Auth token and grant management clients.
• api/resources/selfHosted/ - Credential management for self-hosted Deepgram deployments.
• api/resources/voiceAgent/ - Additional voice-agent resource helpers.
• api/types/ - Shared TypeScript interfaces for all request and response shapes.
• core/ - Internal HTTP fetch wrapper, WebSocket abstraction, retry logic, and header utilities.
• auth/ - Internal authentication helpers used by the client constructors.

Common pitfalls and fixes

• Missing DEEPGRAM_API_KEY: The SDK will throw or return 401s silently; always verify process.env.DEEPGRAM_API_KEY is set before constructing any client.
• ESM .js extension errors: The source uses import ... from "./foo.js" paths; ensure "moduleResolution": "NodeNext" or "Bundler" is set in tsconfig.json, otherwise TypeScript will fail to resolve local imports.
• ws not found at runtime: ws is a runtime dependency; run npm install ws in the consuming project even if @deepgram/sdk is not installed from npm.
• WebSocket connection.connect() must be called after attaching listeners: Attach all .on(...) handlers before calling connection.connect() and await connection.waitForOpen(), or early messages will be missed.
• Self-hosted endpoint: Pass environment: DeepgramEnvironment.SelfHosted and a DeepgramEnvironmentUrls object; forgetting this will route traffic to Deepgram's cloud even in on-prem setups.
• Bundler path aliases not mirroring tsconfig paths: If your bundler (Webpack, Vite, esbuild) does not have the same @deepgram/sdk alias as tsconfig.json, you will get runtime module-not-found errors in production builds.

Vibe-coding prompt template

I have the Deepgram JavaScript SDK source code in `src/deepgram/` and its
integration guide at `USAGE.md`. The upstream package is `@deepgram/sdk@5.1.1`.

Please help me integrate the Deepgram SDK into my existing project step by step:

1. Read `USAGE.md` for the full setup instructions and public API reference.
2. Look at `src/deepgram/index.ts` to understand all available exports.
3. Add the required `ws` dependency to `package.json`.
4. Configure `tsconfig.json` to resolve `@deepgram/sdk` from `src/deepgram/index.ts`.
5. Create a `DeepgramClient` instance using `DEEPGRAM_API_KEY` from environment.
6. Implement the following feature in my project: [DESCRIBE YOUR FEATURE HERE].
7. Add proper error handling using `DeepgramError` and `DeepgramTimeoutError`.
8. Show me the final integration code with all imports sourced from `src/deepgram/`.

My project stack is: [YOUR STACK: e.g. Express + TypeScript + Node 20].

License and credit

The Deepgram JavaScript SDK is released under the MIT License (see source/LICENSE if present, or the upstream repository). Upstream package: @deepgram/sdk on npm — maintained by Deepgram, Inc. Full API documentation at developers.deepgram.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。