> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# ▲ Vercel AI SDK Integration with AssemblyAI
The [AI SDK](https://ai-sdk.dev) gives you a single, unified `transcribe()` API that works across speech-to-text providers. The [`@ai-sdk/assemblyai`](https://ai-sdk.dev/providers/ai-sdk-providers/assemblyai) provider — maintained by Vercel in the [`vercel/ai`](https://github.com/vercel/ai) repo — plugs AssemblyAI's speech models into that API, so you can transcribe audio in any TypeScript or JavaScript project without calling the AssemblyAI API directly.
## Quickstart
Install the AI SDK core package along with the AssemblyAI provider:
```bash theme={null}
npm install ai @ai-sdk/assemblyai
```
```bash theme={null}
yarn add ai @ai-sdk/assemblyai
```
```bash theme={null}
pnpm add ai @ai-sdk/assemblyai
```
```bash theme={null}
bun add ai @ai-sdk/assemblyai
```
You'll need an [AssemblyAI account](https://www.assemblyai.com/dashboard/signup) and an API key from your [dashboard](https://www.assemblyai.com/dashboard/home). The provider reads it from the `ASSEMBLYAI_API_KEY` environment variable:
```bash theme={null}
export ASSEMBLYAI_API_KEY=""
```
Then transcribe a local file with `transcribe()`:
```typescript theme={null}
import { transcribe } from 'ai';
import { assemblyai } from '@ai-sdk/assemblyai';
import { readFile } from 'node:fs/promises';
const result = await transcribe({
model: assemblyai.transcription('universal-3-5-pro'),
audio: await readFile('audio.mp3'),
});
console.log(result.text);
```
`transcribe` is a stable export as of AI SDK v7, which is what `npm install ai`
installs today. The examples on this page target v7.
**Using AI SDK v6?** The examples on this page require v7. AI SDK v6 (and v5) export
only `experimental_transcribe` — `import { transcribe } from 'ai'` throws on those
versions — and the latest provider (`@ai-sdk/assemblyai` 3.x) is built for v7, so it
won't work against v6. If your project is on v6 (for example, an existing project or
a registry policy that hasn't picked up v7 yet), install the v6-compatible packages
and alias the experimental export:
```bash theme={null}
npm install ai@ai-v6 @ai-sdk/assemblyai@ai-v6
```
```typescript theme={null}
import { experimental_transcribe as transcribe } from 'ai';
```
Everything else on this page — the `providerOptions`, model IDs, and result shape —
is the same.
## Configuring the provider
The default `assemblyai` instance reads your key from `ASSEMBLYAI_API_KEY`. To pass the key explicitly — for example, from a secret manager or in a multi-tenant setup — or to add custom headers or a custom `fetch` implementation, create your own provider instance with `createAssemblyAI`:
```typescript theme={null}
import { createAssemblyAI } from '@ai-sdk/assemblyai';
const assemblyai = createAssemblyAI({
apiKey: process.env.ASSEMBLYAI_API_KEY,
});
const result = await transcribe({
model: assemblyai.transcription('universal-3-5-pro'),
audio: await readFile('audio.mp3'),
});
```
## Choosing a speech model
`universal-3-5-pro` is the recommended default. `universal-2` is also supported. Pass the model ID to `assemblyai.transcription()`:
```typescript theme={null}
const model = assemblyai.transcription('universal-3-5-pro');
```
For a breakdown of each model's accuracy, latency, and language support, see [Select the speech model](/pre-recorded-audio/select-the-speech-model).
## Using AssemblyAI features
AssemblyAI's diarization and audio-intelligence features are enabled through `providerOptions.assemblyai`. Option keys are the **camelCase** equivalents of the API's snake\_case parameters (for example, `speaker_labels` → `speakerLabels`, `redact_pii` → `redactPii`):
```typescript theme={null}
import { transcribe } from 'ai';
import {
assemblyai,
type AssemblyAITranscriptionModelOptions,
} from '@ai-sdk/assemblyai';
import { readFile } from 'node:fs/promises';
const result = await transcribe({
model: assemblyai.transcription('universal-3-5-pro'),
audio: await readFile('meeting.mp3'),
providerOptions: {
assemblyai: {
speakerLabels: true,
keytermsPrompt: ['AssemblyAI', 'Universal'],
redactPii: true,
redactPiiPolicies: ['person_name', 'email_address'],
} satisfies AssemblyAITranscriptionModelOptions,
},
});
```
Annotating the options object with `satisfies AssemblyAITranscriptionModelOptions` gives you editor autocomplete and type-checking for the full option set, so you don't have to memorize parameter names or hunt through docs.
The table below reflects `@ai-sdk/assemblyai` 3.0.5. For the always-current list —
including any options added in newer releases — see the
[`@ai-sdk/assemblyai` provider reference](https://ai-sdk.dev/providers/ai-sdk-providers/assemblyai),
which lives alongside the provider code and is the canonical source.
### Transcription options
Every option below is optional and passed under `providerOptions.assemblyai`. Types and behavior follow the AssemblyAI transcription API.
| Option | Type | Description |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audioEndAt` | number | End time of the audio, in milliseconds. |
| `audioStartFrom` | number | Start time of the audio, in milliseconds. |
| `autoChapters` | boolean | Automatically generate chapters for the transcript. |
| `autoHighlights` | boolean | Automatically generate highlights for the transcript. |
| `boostParam` | enum | Boost level for `wordBoost`. Allowed values: `low`, `default`, `high`. **Deprecated** — applies only to the deprecated `wordBoost`; use `keytermsPrompt` instead. |
| `contentSafety` | boolean | Enable content safety filtering. |
| `contentSafetyConfidence` | number | Confidence threshold for content safety filtering (25-100). |
| `customSpelling` | array of objects | Custom spelling rules. Each object has `from` (array of strings) and `to` (string). |
| `disfluencies` | boolean | Include disfluencies (um, uh, etc.) in the transcript. |
| `domain` | string | Enable a domain-specific model for specialized terminology. Currently supports `medical-v1` (Medical Mode). |
| `entityDetection` | boolean | Detect entities in the transcript. |
| `filterProfanity` | boolean | Filter profanity in the transcript. |
| `formatText` | boolean | Apply text formatting to the transcript. |
| `iabCategories` | boolean | Include IAB categories in the transcript. |
| `keytermsPrompt` | array of strings | Domain-specific keyterms to boost recognition for (max 6 words per phrase). Replaces `wordBoost` for newer models — supported by `universal-3-pro`, `universal-3-5-pro`, and `slam-1` (and `universal-2` when enabled). |
| `languageCode` | string | Language code for the audio. Supports numerous ISO-639-1 and ISO-639-3 codes. |
| `languageConfidenceThreshold` | number | Confidence threshold for language detection. |
| `languageDetection` | boolean | Enable automatic language detection. |
| `languageDetectionOptions` | object | Options for language detection: `expectedLanguages` (array of strings), `fallbackLanguage` (string), `codeSwitching` (boolean), `codeSwitchingConfidenceThreshold` (number, 0-1). |
| `multichannel` | boolean | Process multiple audio channels separately. |
| `prompt` | string | Natural-language context (up to 1,500 words) to steer the model. Only supported by `universal-3-pro`, `universal-3-5-pro`, and `slam-1`. |
| `punctuate` | boolean | Add punctuation to the transcript. |
| `redactPii` | boolean | Redact personally identifiable information (PII). |
| `redactPiiAudio` | boolean | Redact PII in the audio file. |
| `redactPiiAudioOptions` | object | Options for PII-redacted audio: `returnRedactedNoSpeechAudio` (boolean), `overrideAudioRedactionMethod` (`silence`). Requires `redactPiiAudio`. |
| `redactPiiAudioQuality` | enum | Quality of the redacted audio file. Allowed values: `mp3`, `wav`. |
| `redactPiiPolicies` | array of enums | Which types of information to redact (e.g. `person_name`, `phone_number`). |
| `redactPiiReturnUnredacted` | boolean | Return the original unredacted transcript alongside the redacted one. Requires `redactPii`. |
| `redactPiiSub` | enum | Substitution method for redacted PII. Allowed values: `entity_name`, `hash`. |
| `redactStaticEntities` | object | Map of user-defined labels to exact terms to redact, e.g. `{ INTERNAL_TOOL: ['Bearclaw'] }`. Applied on top of standard PII redaction. Requires `redactPii`. |
| `removeAudioTags` | enum | Remove inline annotations from rich transcripts. Allowed values: `all`, `speaker`. Universal-3 Pro models. |
| `sentimentAnalysis` | boolean | Perform sentiment analysis on the transcript. |
| `speakerLabels` | boolean | Label different speakers in the transcript (diarization). |
| `speakerOptions` | object | Diarization options: `minSpeakersExpected` (number), `maxSpeakersExpected` (number). |
| `speakersExpected` | number | Expected number of speakers in the audio. |
| `speechThreshold` | number | Threshold for speech detection (0-1). |
| `summarization` | boolean | Generate a summary of the transcript. |
| `summaryModel` | enum | Summarization model. Allowed values: `informative`, `conversational`, `catchy`. |
| `summaryType` | enum | Type of summary. Allowed values: `bullets`, `bullets_verbose`, `gist`, `headline`, `paragraph`. |
| `temperature` | number | Sampling temperature (0-1) controlling randomness. Universal-3 Pro models. |
| `webhookAuthHeaderName` | string | Name of the authentication header for webhook requests. |
| `webhookAuthHeaderValue` | string | Value of the authentication header for webhook requests. |
| `webhookUrl` | string | URL to send webhook notifications to. |
| `wordBoost` | array of strings | Words to boost in the transcript. **Deprecated** — rejected by `universal-3-pro`, `universal-3-5-pro`, and `slam-1` (works only on `universal-2`/`best`); use `keytermsPrompt` instead. |
## Getting the full results back
`transcribe()` returns a provider-agnostic result, but AssemblyAI's richer output — utterances, entities, sentiment, and more — is preserved, so you don't lose anything by going through the AI SDK:
* **Top-level fields** like `result.text`, `result.segments`, and `result.durationInSeconds` are normalized across providers.
* **`result.providerMetadata.assemblyai`** holds AssemblyAI-specific results such as `utterances`, `entities`, and `sentimentAnalysisResults`.
* **`result.response.body`** is the complete, raw AssemblyAI transcript object.
```typescript theme={null}
const result = await transcribe({
model: assemblyai.transcription('universal-3-5-pro'),
audio: await readFile('meeting.mp3'),
providerOptions: {
assemblyai: { speakerLabels: true, sentimentAnalysis: true },
},
});
// Normalized, provider-agnostic fields
console.log(result.text);
console.log(result.segments);
// AssemblyAI-specific results
const { utterances, sentimentAnalysisResults } =
result.providerMetadata.assemblyai;
// The complete, raw AssemblyAI transcript
const rawTranscript = result.response.body;
```
Timestamps use **different units depending on where you read them.** The top-level
`result.segments` are in **seconds** (the AI SDK's normalized format), while every
timing inside `result.providerMetadata.assemblyai` and `result.response.body` is in
**milliseconds** (AssemblyAI's native format). Convert accordingly when you combine
the two.
## Additional resources
* [AssemblyAI provider reference on ai-sdk.dev](https://ai-sdk.dev/providers/ai-sdk-providers/assemblyai) — the canonical, complete list of provider options
* [`vercel/ai` on GitHub](https://github.com/vercel/ai) — the AI SDK source and where the provider is maintained
* [AssemblyAI API reference](/api-reference/overview) — the underlying transcription API and every parameter it accepts