The official JavaScript/TypeScript SDK for Deepgram's automated speech recognition, text-to-speech, and language understanding APIs. Power your applications with world-class speech and Language AI models.
Comprehensive API documentation and guides are available at developers.deepgram.com.
Install the Deepgram JavaScript SDK using npm:
npm install @deepgram/sdk- REST API Reference - Fern-generated methods and parameters for HTTP endpoints
Every streaming client exposes both connect() and createConnection(). They are aliases that return a start-closed socket: register handlers, call the socket's connect(), and then await waitForOpen() before sending data.
All sockets expose on("open" | "message" | "close" | "error", callback), off(event, callback), connect(), waitForOpen(), close(), readyState, and a lower-level socket property. Registering on() again for the same event replaces the prior callback. Prefer the typed send methods below instead of calling socket.send() directly.
Pass shouldReconnect: (event) => boolean when a connection needs a custom close policy. Native Flux Listen V2 automatically treats the server no-status (1005) close after sendCloseStream() as terminal; other native socket closes retain the default retry behavior. Custom transports disable wrapper retries by default; with reconnect: true, a 1005 close after CloseStream or TTS Close is terminal unless shouldReconnect overrides it.
| Service | Create a socket | Typed send methods |
|---|---|---|
| Voice Agent v1 | client.agent.v1.connect() or .createConnection() |
sendSettings, sendUpdateListen, sendUpdateThink, sendUpdateSpeak, sendInjectUserMessage, sendInjectAgentMessage, sendFunctionCallResponse, sendKeepAlive, sendUpdatePrompt, sendForceEndTurn, sendMedia |
| Speech-to-Text v1 | client.listen.v1.connect(args) or .createConnection(args) |
sendMedia, sendFinalize, sendCloseStream, sendKeepAlive |
| Flux STT v2 (conversational) | client.listen.v2.connect(args) or .createConnection(args) |
sendMedia, sendCloseStream, sendForceEndTurn, sendConfigure |
| Text-to-Speech v1 | client.speak.v1.connect(args) or .createConnection(args) |
sendText, sendFlush, sendClear, sendClose |
| Flux TTS v2 | client.speak.v2.connect(args) or .createConnection(args) |
sendSpeak, sendFlush, sendInterrupt, sendConfigure, sendClose |
The public connection argument types and Deepgram-specific wrapper behavior are defined in src/CustomClient.ts. Use the linked socket classes for exact message and event types.
For Voice Agent function calls, do not send FunctionCallResponse for an ID listed in a FunctionCallCancelled event. Set defer_until_eot: true on an agent.think.functions entry when its action cannot be undone: the agent waits until the user's turn is confirmed, and discards the deferred call if that turn resumes.
The Deepgram SDK provides clients for all major use cases:
Connect to our WebSocket and transcribe live streaming audio:
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const connection = await client.listen.v1.connect({
model: "nova-3",
language: "en",
punctuate: "true",
interim_results: "true",
});
connection.on("open", () => console.log("Connection opened"));
connection.on("message", (data) => {
if (data.type === "Results") {
console.log(data);
}
});
connection.connect();
await connection.waitForOpen();
// Send audio data
connection.sendMedia(audioData);Pass an abortSignal to stop a connection attempt or active session and disable automatic reconnection. If you await waitForOpen(), make that wait abort-aware as shown in Canceling a WebSocket Connection (AbortSignal).
Every streaming connection is also an async iterable, so it can be consumed with for await
instead of a callback:
const connection = await client.listen.v1.connect({ model: "nova-3", interim_results: "true" });
connection.connect();
await connection.waitForOpen();
for await (const message of connection) {
if (message.type === "Results" && message.is_final) {
console.log(message.channel.alternatives[0].transcript);
}
}Iteration ends when the connection closes, throws if it errors, and break closes the
connection. Messages that arrive while your loop body is still running are buffered rather
than dropped, and on("message", ...) keeps working alongside iteration if you want both.
Each connection supports one active iterator. Its queue is capped at 1,000 messages or 16 MiB;
an overflow throws and closes the connection rather than retaining unbounded audio in memory.
This works on listen.v1, listen.v2, agent.v1, speak.v1 and speak.v2; on the sockets
that carry audio, binary frames are delivered as a Blob.
Transcribe pre-recorded audio files (API Reference):
import { createReadStream } from "fs";
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const response = await client.listen.v1.media.transcribeFile(
createReadStream("audio.wav"),
{ model: "nova-3" }
);
console.log(response.results.channels[0].alternatives[0].transcript);Generate natural-sounding speech from text (API Reference):
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const response = await client.speak.v1.audio.generate({
text: "Hello, this is a sample text to speech conversion.",
model: "aura-2-thalia-en",
encoding: "linear16",
container: "wav",
});
// Save the audio file
const stream = response.stream();Analyze text for sentiment, topics, and intents (API Reference):
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const response = await client.read.v1.text.analyze({
text: "Hello, world!",
language: "en",
});Build interactive voice agents:
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const connection = await client.agent.v1.connect();
connection.on("open", () => console.log("Connection opened"));
connection.on("message", (data) => {
if (data.type === "ConversationText") {
console.log(data);
}
});
connection.connect();
await connection.waitForOpen();
connection.sendSettings({
type: "Settings",
audio: {
input: { encoding: "linear16", sample_rate: 24000 },
output: { encoding: "linear16", sample_rate: 16000, container: "wav" },
},
agent: {
language: "en",
listen: {
provider: { type: "deepgram", version: "v1", 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" },
},
},
});The Deepgram SDK supports two authentication methods:
Use your Deepgram API key for server-side applications:
import { DeepgramClient } from "@deepgram/sdk";
// Explicit API key
const client = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
// Or via environment variable DEEPGRAM_API_KEY
const client = new DeepgramClient();Use access tokens for temporary or scoped access (recommended for client-side applications):
import { DeepgramClient } from "@deepgram/sdk";
// Explicit access token
const client = new DeepgramClient({ accessToken: "YOUR_ACCESS_TOKEN" });
// Or via environment variable DEEPGRAM_ACCESS_TOKEN
const client = new DeepgramClient();
// Generate access tokens using your API key
const authClient = new DeepgramClient({ apiKey: "YOUR_API_KEY" });
const tokenResponse = await authClient.auth.v1.tokens.grant();
const tokenClient = new DeepgramClient({ accessToken: tokenResponse.access_token });The SDK automatically discovers credentials from these environment variables:
DEEPGRAM_ACCESS_TOKEN- Your access token (takes precedence)DEEPGRAM_API_KEY- Your Deepgram API key
Precedence: Explicit parameters > Environment variables
To access the Deepgram API you will need a free Deepgram API Key.
The SDK works in modern browsers with some considerations:
- 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
Due to CORS header restrictions in the Deepgram API, you must use a proxy server when making REST API calls from browsers. Pass "proxy" as your API key and point baseUrl to your proxy:
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient({
apiKey: "proxy",
baseUrl: "http://localhost:8080",
});Your proxy must set the Authorization: token DEEPGRAM_API_KEY header and forward requests to Deepgram's API. See our example Deepgram Node Proxy.
<!-- CDN (UMD) -->
<script src="https://cdn.jsdelivr.net/npm/@deepgram/sdk"></script>
<script>
const { DeepgramClient } = deepgram;
</script>
<!-- CDN (ESM) -->
<script type="module">
import { DeepgramClient } from "https://cdn.jsdelivr.net/npm/@deepgram/sdk/+esm";
</script>When the API returns a non-success status code (4xx or 5xx), a DeepgramError is thrown:
import { DeepgramClient, DeepgramError } from "@deepgram/sdk";
const client = new DeepgramClient();
try {
await client.listen.v1.media.transcribeFile(audioData, { model: "nova-3" });
} catch (err) {
if (err instanceof DeepgramError) {
console.log(err.statusCode);
console.log(err.message);
console.log(err.body);
}
}The SDK exports all request and response types as TypeScript interfaces:
// Direct import (recommended)
import { ListenV1Response, SpeakV1Response } from "@deepgram/sdk";
// Or via namespace
import { Deepgram } from "@deepgram/sdk";
type Response = Deepgram.ListenV1Response;Configure timeouts, retries, and other request options:
const response = await client.listen.v1.media.transcribeFile(audioData, {
model: "nova-3",
timeoutInSeconds: 60,
maxRetries: 3,
});All real-time connect() methods — listen.v1.connect(), listen.v2.connect(),
agent.v1.connect(), speak.v1.connect(), and speak.v2.connect() — accept an
abortSignal. Use it when cancellation must be controlled outside the connection owner,
such as in apps that start and stop sessions rapidly.
When the signal aborts, the SDK stops the pending or active transport and disables automatic
reconnection. A registered close callback can run as part of cancellation. AbortSignal does
not clear callbacks registered with connection.on(), and waitForOpen() does not observe the
signal directly. If a connection can be canceled while opening, make the wait abort-aware:
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient();
const controller = new AbortController();
function waitForOpenOrAbort(
connection: { waitForOpen(): Promise<unknown> },
signal: AbortSignal,
): Promise<void> {
return new Promise((resolve, reject) => {
const cleanup = () => signal.removeEventListener("abort", onAbort);
const onAbort = () => {
cleanup();
reject(signal.reason ?? new Error("Connection aborted"));
};
if (signal.aborted) {
onAbort();
return;
}
signal.addEventListener("abort", onAbort, { once: true });
connection.waitForOpen().then(
() => {
cleanup();
resolve();
},
(error) => {
cleanup();
reject(error);
},
);
});
}
const connection = await client.listen.v1.connect({
model: "nova-3",
language: "en",
abortSignal: controller.signal,
});
connection.on("open", () => console.log("Connection opened"));
connection.on("message", (data) => console.log(data));
connection.connect();
await waitForOpenOrAbort(connection, controller.signal);
// Cancel the session later. If this happens before open, the helper above rejects.
controller.abort();An aborted signal is terminal for that connection. To start a new session, create a fresh
AbortController and connection. AbortSignal does not provide removeAllListeners(); manage
the lifecycle of callbacks registered on the old connection separately.
const { data, rawResponse } = await client.listen.v1.media
.transcribeFile(audioData, { model: "nova-3" })
.withRawResponse();
console.log(rawResponse.headers["X-My-Header"]);Use a custom fetch implementation for unsupported environments:
import { DeepgramClient } from "@deepgram/sdk";
const client = new DeepgramClient({
apiKey: "YOUR_API_KEY",
fetcher: yourCustomFetchImplementation,
});In Node.js you can route streaming WebSocket connections (listen, speak, agent)
through any compatible custom http.Agent implementation. For example, install a
Node 18-compatible version of https-proxy-agent:
npm install https-proxy-agent@8Then create an HttpsProxyAgent to route traffic through a corporate HTTP/HTTPS
egress proxy. Set agent on the client to apply it to every connection, or pass it
per connection to override the client-level default:
import { DeepgramClient } from "@deepgram/sdk";
import { HttpsProxyAgent } from "https-proxy-agent";
const agent = new HttpsProxyAgent(process.env.HTTPS_PROXY!);
// Applies to every streaming connection from this client.
const client = new DeepgramClient({ apiKey: "YOUR_API_KEY", agent });
// ...or per connection (overrides the client-level agent).
const socket = await client.listen.v1.createConnection({ model: "nova-3", agent });The agent option is Node-only; it is ignored in browser and web-worker runtimes,
which use the native WebSocket and cannot accept a custom agent.
import { DeepgramClient, logging } from "@deepgram/sdk";
const client = new DeepgramClient({
apiKey: "YOUR_API_KEY",
logging: {
level: logging.LogLevel.Debug,
logger: new logging.ConsoleLogger(),
silent: false,
},
});The SDK works in the following runtimes:
- Node.js 18+
- Vercel
- Cloudflare Workers
- Deno v1.25+
- Bun 1.0+
- React Native
We welcome contributions to improve this SDK! However, please note that this library is primarily generated from our API specifications.
-
Install dependencies:
pnpm install
-
Build:
make build
-
Run tests:
make test
See our CONTRIBUTING guide.
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.
We love to hear from you so if you have questions, comments or find a bug in the project, let us know!
Please see our community code of conduct before contributing to this project.
This project is licensed under the MIT License - see the LICENSE file for details.