Official JavaScript SDK for Deepgram. Power your apps with world-class speech and Language AI models.
- Migrating from earlier versions
- Installation
- Initialization
- Scoped Configuration
- Transcription (Synchronous)
- Transcription (Asynchronous / Callbacks)
- Transcription (Live / Streaming)
- Transcribing to captions
- Text to Speech
- Text Intelligence
- Projects
- Keys
- Members
- Scopes
- Invitations
- Usage
- Billing
- On-Prem APIs
- Backwards Compatibility
- Development and Contributing
- Getting Help
We have published a migration guide on our docs, showing how to move from v2 to v3.
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.
You can install this SDK directly from npm.
npm install @deepgram/sdk
# - or -
# yarn add @deepgram/sdkYou 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>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>import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");
const deepgram = createClient(DEEPGRAM_API_KEY);🔑 To access the Deepgram API you will need a free Deepgram API Key.
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:
- The
globalnamespace 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
globaldefaults are used.
- Each namespace (
listen,manage,onprem,read,speak) can have its specific configurations which override theglobalsettings within their respective scopes. - Allows for detailed control over different parts of the application interacting with various Deepgram API endpoints.
- Configurations for both
fetchandwebsocketcan be specified under each namespace, allowing different transport mechanisms for different operations. - For example, the
fetchconfiguration can have its own URL and proxy settings distinct from thewebsocket. - The generic interfaces define a structure for transport options which include a client (like a
fetchorWebSocketinstance) 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.
Useful for using different API environments (for e.g. beta).
import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");
const deepgram = createClient(DEEPGRAM_API_KEY, {
global: { fetch: { options: { url: "https://api.beta.deepgram.com" } } },
});Useful for on-prem installations. Only affects requests to /listen endpoints.
import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");
const deepgram = createClient(DEEPGRAM_API_KEY, {
listen: { fetch: { options: { url: "http://localhost:8080" } } },
});Useful for providing a custom http client.
import { createClient } from "@deepgram/sdk";
// - or -
// const { createClient } = require("@deepgram/sdk");
const yourFetch = async () => {
return Response("...etc");
};
const deepgram = createClient(DEEPGRAM_API_KEY, {
global: { fetch: { client: yourFetch } },
});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", {
global: { fetch: { options: { proxy: { url: "http://localhost:8080" } } } },
});Important: You must pass
"proxy"as your API key, and use the proxy to set theAuthorizationheader 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.
Useful for many things.
import { createClient } from "@deepgram/sdk";
const deepgram = createClient("proxy", {
global: { fetch: { options: { headers: { "x-custom-header": "foo" } } } },
});const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
{
url: "https://dpgr.am/spacewalk.wav",
},
{
model: "nova",
}
);See our API reference for more info.
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.
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.
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.
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.
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.
const { result } = await deepgram.speak.request({ text }, { model: "aura-asteria-en" });const dgConnection = deepgram.speak.live({ model: "aura-asteria-en" });
dgConnection.on(LiveTTSEvents.Open, () => {
console.log("Connection opened");
// Send text data for TTS synthesis
dgConnection.sendText(text);
// Send Flush message to the server after sending the text
dgConnection.flush();
dgConnection.on(LiveTTSEvents.Close, () => {
console.log("Connection closed");
});
});See our API reference for more info.
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. In an article titled "Current Notes" in the February 9, 1885, edition,
the phrase is mentioned as a good practice sentence for writing students: "A
favorite copy set by writing teachers for their pupils is the following,
because it contains every letter of the alphabet: 'A quick brown fox jumps over
the lazy dog.'" Dozens of other newspapers published the phrase over the
next few months, all using the version of the sentence starting with "A" rather
than "The". The earliest known use of the phrase starting with "The" is from
the 1888 book Illustrative Shorthand by Linda Bronson.[3] The modern form
(starting with "The") became more common even though it is slightly longer than
the original (starting with "A").`;
const { result, error } = await deepgram.read.analyzeText(
{ text },
{ language: "en", topics: true, sentiment: true }
);See our API reference for more info.
Returns all projects accessible by the API key.
const { result, error } = await deepgram.manage.getProjects();See our API reference for more info.
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 a project.
const { result, error } = await deepgram.manage.updateProject(projectId, options);See our API reference for more info.
Delete a project.
const { error } = await deepgram.manage.deleteProject(projectId);See our API reference for more info.
Retrieves all keys associated with the provided project_id.
const { result, error } = await deepgram.manage.getProjectKeys(projectId);See our API reference for more info.
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.
Creates an API key with the provided scopes.
const { result, error } = await deepgram.manage.createProjectKey(projectId, options);See our API reference for more info.
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.
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.
Removes member account for specified member_id.
const { error } = await deepgram.manage.removeProjectMember(projectId, projectMemberId);See our API reference for more info.
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.
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.
Retrieves all invitations associated with the provided project_id.
const { result, error } = await deepgram.manage.getProjectInvites(projectId);See our API reference for more info.
Sends an invitation to the provided email address.
const { result, error } = await deepgram.manage.sendProjectInvite(projectId, options);See our API reference for more info.
Removes the specified invitation from the project.
const { error } = await deepgram.manage.deleteProjectInvite(projectId, email);See our API reference for more info.
Removes the authenticated user from the project.
const { result, error } = await deepgram.manage.leaveProject(projectId);See our API reference for more info.
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.
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.
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.
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.
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.
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.
const { result, error } = await deepgram.onprem.listCredentials(projectId);const { result, error } = await deepgram.onprem.getCredentials(projectId, credentialId);const { result, error } = await deepgram.onprem.createCredentials(projectId, options);const { result, error } = await deepgram.onprem.deleteCredentials(projectId, credentialId);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 strictly follow semver, and will not introduce breaking changes to the publicly documented interfaces of the SDK. Use internal and undocumented interfaces without pinning your version, at your own risk.
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.
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.
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:
