---

AssemblyAI JavaScript SDK

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

Claude Code

This repository includes a CLAUDE.md file that provides context to Claude Code about this SDK — key APIs, common patterns, and gotchas. When you open this repo in Claude Code, it automatically reads this file to give better assistance.

Using with AI coding agents

If you're integrating this SDK with Claude Code, Cursor, Copilot, or another AI coding assistant, give your agent current API context so it doesn't generate code against outdated model names or parameters.

The most effective option is project instructions. Add this to your CLAUDE.md, .cursorrules, AGENTS.md, or equivalent agent instructions file:

Always fetch https://assemblyai.com/docs/llms.txt before writing AssemblyAI code. The API has changed, do not rely on memorized parameter names.

For on-demand documentation lookups during a session, connect the AssemblyAI docs MCP server:

claude mcp add assemblyai-docs --transport http https://mcp.assemblyai.com/docs

For deep SDK context in Claude Code specifically, install the AssemblyAI skill:

claude install-skill https://github.com/AssemblyAI/assemblyai-skill

See Coding agent prompts for Cursor setup, MCP tool details, and tips for best results.

Documentation

Visit the AssemblyAI documentation for step-by-step instructions and a lot more details about our AI models and API. Explore the SDK API reference for more details on the SDK types, functions, and classes.

Quickstart

Install the AssemblyAI SDK using your preferred package manager:

npm install assemblyai

yarn add assemblyai

pnpm add assemblyai

bun add assemblyai

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

import{AssemblyAI}from"assemblyai";constbaseUrl="https://api.assemblyai.com";constclient=newAssemblyAI({apiKey: "YOUR_API_KEY",baseUrl: baseUrl,});

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.

<!-- Unminified full SDK --><scriptsrc="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.umd.js"></script><!-- Minified full SDK --><scriptsrc="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.umd.min.js"></script><!-- Unminified Streaming STT only --><scriptsrc="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.streaming.umd.js"></script><!-- Minified Streaming STT only --><scriptsrc="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.streaming.umd.min.js"></script>

The script creates a global assemblyai variable containing all the services. Here's how you create a StreamingTranscriber object.

const{ StreamingTranscriber }=assemblyai;consttranscriber=newStreamingTranscriber({token: "[GENERATE TEMPORARY AUTH TOKEN IN YOUR API]",
...
});

For type support in your IDE, see Reference types from JavaScript.

Speech-To-Text

Transcribe audio and video files

Transcribe an audio file with a public URL

When you create a transcript, you can either pass in a URL to an audio file or upload a file directly.

// Transcribe file at remote URLconstaudioFile="https://assembly.ai/sports_injuries.mp3";constparams={audio: audioFile,speech_models: ["universal-3-5-pro","universal-2"],language_detection: true,};construn=async()=>{consttranscript=awaitclient.transcripts.transcribe(params);console.log(transcript.text);};run();

[!NOTE] You can also pass a local file path, a stream, or a buffer as the audio property.

transcribe queues a transcription job and polls it until the status is completed or error.

If you don't want to wait until the transcript is ready, you can use submit:

lettranscript=awaitclient.transcripts.submit({audio: "https://assembly.ai/espn.m4a",speech_models: ["universal-3-5-pro","universal-2"],language_detection: true,});

Transcribe a local audio file

When you create a transcript, you can either pass in a URL to an audio file or upload a file directly.

// Upload a file via local path and transcribelettranscript=awaitclient.transcripts.transcribe({audio: "./news.mp4",speech_models: ["universal-3-5-pro","universal-2"],language_detection: true,});

Note: You can also pass a file URL, a stream, or a buffer as the audio property.

transcribe queues a transcription job and polls it until the status is completed or error.

If you don't want to wait until the transcript is ready, you can use submit:

lettranscript=awaitclient.transcripts.submit({audio: "./news.mp4",speech_models: ["universal-3-5-pro","universal-2"],language_detection: true,});

Enable additional Speech Understanding models

You can extract even more insights from the audio by enabling any of our Speech Understanding models using transcription options. For example, here's how to enable Speaker diarization model to detect who said what.

import{AssemblyAI}from"assemblyai";constclient=newAssemblyAI({apiKey: "<YOUR_API_KEY>",});constaudioFile="https://assembly.ai/wildfires.mp3";constparams={audio: audioFile,speech_models: ["universal-3-5-pro","universal-2"],language_detection: true,speaker_labels: true,};construn=async()=>{consttranscript=awaitclient.transcripts.transcribe(params);for(constutteranceoftranscript.utterances!){console.log(`Speaker ${utterance.speaker}: ${utterance.text}`);}};run();

Get a transcript

This will return the transcript object in its current state. If the transcript is still processing, the status field will be queued or processing. Once the transcript is complete, the status field will be completed.

consttranscript=awaitclient.transcripts.get(transcript.id);

If you created a transcript using .submit(), you can still poll until the transcript status is completed or error using .waitUntilReady():

consttranscript=awaitclient.transcripts.waitUntilReady(transcript.id,{// How frequently the transcript is polled in ms. Defaults to 3000.pollingInterval: 1000,// How long to wait in ms until the "Polling timeout" error is thrown. Defaults to infinite (-1).pollingTimeout: 5000,});

Get sentences and paragraphs

constsentences=awaitclient.transcripts.sentences(transcript.id);const{ paragraphs }=awaitclient.transcripts.paragraphs(transcript.id);for(constparagraphofparagraphs){console.log(paragraph.text);}for(constsentenceofsentences){console.log(sentence.text);}

Get subtitles

constcharsPerCaption=32;letsrt=awaitclient.transcripts.subtitles(transcript.id,"srt");srt=awaitclient.transcripts.subtitles(transcript.id,"srt",charsPerCaption);letvtt=awaitclient.transcripts.subtitles(transcript.id,"vtt");vtt=awaitclient.transcripts.subtitles(transcript.id,"vtt",charsPerCaption);

List transcripts

This will return a page of transcripts you created.

constpage=awaitclient.transcripts.list();

You can also paginate over all pages.

letpreviousPageUrl: string|null=null;do{constpage=awaitclient.transcripts.list(previousPageUrl);previousPageUrl=page.page_details.prev_url;}while(previousPageUrl!==null);

[!NOTE] To paginate over all pages, you need to use the page.page_details.prev_url because the transcripts are returned in descending order by creation date and time. The first page is are the most recent transcript, and each "previous" page are older transcripts.

Delete a transcript

constres=awaitclient.transcripts.delete(transcript.id);

Transcribe audio synchronously

client.sync posts a whole audio file and returns the finished transcript in one round trip — no job id, no polling. Use it for short clips where you want the answer inline; use client.transcripts for long-form audio, URLs, or the rich audio-intelligence features the sync API doesn't expose.

constresult=awaitclient.sync.transcribe("./call.wav");console.log(result.text,result.session_id);

The input can be a local file path, raw audio bytes, a Blob, or a readable stream — but not a URL.

Configure the transcription

constresult=awaitclient.sync.transcribe("./call.wav",{prompt: "Transcribe verbatim. Preserve disfluencies.",// max 4096 charskeyterms_prompt: ["AssemblyAI","Lemur"],// max 2048 chars totallanguage_codes: ["es"],// or e.g. ["en", "es"] for multilingual; defaults to Englishconversation_context: [// prior turns, oldest first"I'd like to book a flight to Denver.","Sure, what date were you thinking?",],});

Raw S16LE PCM audio needs sample_rate and channels; WAV reads them from its header.

constresult=awaitclient.sync.transcribe(rawPcmBytes,{sample_rate: 16_000,channels: 1,});

Get word timestamps

Word timestamps are opt-in. By default each word in result.words carries text and confidence only — start/end are absent. Set timestamps: true to get accurate per-word timings at a small latency cost.

constresult=awaitclient.sync.transcribe("./call.wav",{timestamps: true,});for(constwordofresult.words){console.log(word.text,word.start,word.end);// milliseconds}

Pre-warm the connection

The sync API is a single request/response, so a transcribe() that connects on demand pays the full DNS + TCP + TLS handshake on the critical path. Call warm() as soon as you know audio is coming — for example while it is still being recorded — so the next transcribe() reuses the open connection.

awaitclient.sync.warm();// fire as recording startsconstaudio=awaitrecordUntilDone();constresult=awaitclient.sync.transcribe(audio);// reuses the hot connection

Handle errors

Failures throw a SyncTranscriptError with the HTTP status, a machine-readable errorCode (bad_audio, audio_too_large, capacity_exceeded, …), and retryAfter (seconds) on 429/503 responses.

import{SyncTranscriptError}from"assemblyai";try{constresult=awaitclient.sync.transcribe("./call.wav");}catch(error){if(errorinstanceofSyncTranscriptError){console.error(error.status,error.errorCode,error.retryAfter);}}

Transcribe streaming audio

Refer to AssemblyAI's streaming documentation for full code examples.

Create the streaming transcriber.

consttranscriber=client.streaming.transcriber({speechModel: "universal-3-5-pro",sampleRate: 16_000,});

Warning

Storing your API key in client-facing applications exposes your API key. Generate a temporary auth token on the server and pass it to your client. Server code:

consttoken=awaitclient.streaming.createTemporaryToken({
expires_in_seconds =60,});// TODO: return token to client

Client code:

import{StreamingTranscriber}from"assemblyai";// TODO: implement getToken to retrieve token from serverconsttoken=awaitgetToken();consttranscriber=newStreamingTranscriber({
token,});

You can configure the following events.

transcriber.on("open",({ id, expires_at })=>console.log('Session ID:',id,'Expires at:',expires_at));transcriber.on("close",(code: number,reason: string)=>console.log('Closed',code,reason));transcriber.on("turn",({ transcript })=>console.log('Transcript:',transcript));transcriber.on("error",(error: Error)=>console.error('Error',error));

After configuring your events, connect to the server.

awaittranscriber.connect();

Send audio data via chunks.

// Pseudo code for getting audiogetAudio((chunk)=>{transcriber.sendAudio(chunk);});

Or send audio data via a stream:

audioStream.pipeTo(transcriber.stream());

Close the connection when you're finished.

awaittranscriber.close();

Contributing

If you want to contribute to the JavaScript SDK, follow the guidelines in CONTRIBUTING.md.