JavaScript SDK Reference

The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription, as well as the latest LeMUR models. It is written primarily for Node.js in TypeScript with all types exported, but also compatible with other runtimes.

Installation

Install the AssemblyAI SDK using your preferred package manager:

$
npm install assemblyai

Then, import the assemblyai module and create an AssemblyAI object with your API key:

1
import { AssemblyAI } from "assemblyai";
2
3
const client = new AssemblyAI({
4
  apiKey: process.env.ASSEMBLYAI_API_KEY,
5
});

You can now use the client object to interact with the AssemblyAI API.

Using a CDN

You can use automatic CDNs like UNPKG to load the library from a script tag.

• Replace :version with the desired version or latest.
• Remove .min to load the non-minified version.
• Remove .streaming to load the entire SDK. Keep .streaming to load the Streaming STT specific version.

1
<!-- Unminified full SDK -->
2
<script src="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.umd.js"></script>
3
<!-- Minified full SDK -->
4
<script src="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.umd.min.js"></script>
5
<!-- Unminified Streaming STT only -->
6
<script src="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.streaming.umd.js"></script>
7
<!-- Minified Streaming STT only -->
8
<script src="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.streaming.umd.min.js"></script>

Compatibility

The JavaScript SDK is developed for Node.js but is also compatible with other runtimes such as the browser, Deno, Bun, Cloudflare Workers, etc.

Node.js compatibility

The SDK supports Node.js 18, 20, and 21. If you do use an older version of Node.js like version 16, you’ll need to polyfill fetch.

Browser compatibility

To make the SDK compatible with the browser, the SDK aims to use web standards as much as possible. However, there are still incompatibilities between Node.js and the browser.

• RealtimeTranscriber doesn’t support the AssemblyAI API key in the browser. Instead, you have to generate a temporary auth token using client.realtime.createTemporaryToken, and pass in the resulting token to the real-time transcriber.

  Generate a temporary auth token on the server.

  1
  import { AssemblyAI } from "assemblyai"
  2
  // Ideally, to avoid embedding your API key client side,
  3
  // you generate this token on the server, and pass it to the client via an API.
  4
  const client = new AssemblyAI({ apiKey: "YOUR_API_KEY" });
  5
  const token = await client.realtime.createTemporaryToken({ expires_in = 480 });

  [!NOTE] We recommend generating the token on the server, so you don’t embed your AssemblyAI API key in your client app. If you embed the API key on the client, everyone can see it and use it for themselves.

  Then pass the token via an API to the client. On the client, create an instance of RealtimeTranscriber using the token.

  1
  import { RealtimeTranscriber } from "assemblyai";
  2
  // or the following if you're using UMD
  3
  // const { RealtimeTranscriber } = assemblyai;
  4
  5
  const token = getToken(); // getToken is a function for you to implement
  6
  7
  const rt = new RealtimeTranscriber({
  8
    token: token,
  9
  });

• You can’t pass local audio file paths to client.files.upload, client.transcripts.transcribe, and client.transcripts.submit. If you do, you’ll get the following error: “Interacting with the file system is not supported in this environment.”. If you want to transcribe audio files, you must use a public URL, a stream, or a buffer.

Deno, Bun, Cloudflare Workers, etc.

Most server-side JavaScript runtimes include a compatibility layer with Node.js. Our SDK is developed for Node.js, which makes it compatible with other runtimes through their compatibility layer. The bugs in these compatibility layers may introduce issues in our SDK.