<!-- BusyBot node reference — https://busybot.net/tools/assemblyai/ -->

> Node: AssemblyAI (`assemblyai`) · Action (binary) · v1
> Category: Utility · Credentials: AssemblyAI API (`assemblyaiApi`)
> Updated: 2026-08-16

# AssemblyAI

> Transcribe audio, analyze content, and interact with LLM gateway using AssemblyAI

## Overview

The AssemblyAI tool provides comprehensive speech-to-text transcription, audio intelligence features (sentiment analysis, entity detection, auto chapters, content safety, PII redaction, summarization), and an LLM gateway for chat completions and understanding. It supports async transcript creation with built-in polling, file upload for audio binary data, subtitle export (SRT/VTT), redacted audio download, word search, and paragraph/sentence segmentation. Uses the AssemblyAI REST API v2 with API key authentication.

**Category:** Utility  
**Tool Name:** `assemblyai`  
**Version:** 1

**Appearance:** Icon: `lucide-Headphones` | Color: `#2545D3`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **AssemblyAI API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/assemblyai-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| File | `file` |
| Transcript | `transcript` |
| LLM Gateway | `llmGateway` |

### Operations

Every operation belongs to one resource: `File` offers Upload, `Transcript` offers the nine transcript operations, and `LLM Gateway` offers Chat Completions and Understanding.

| Operation | Value | Description |
|-----------|-------|-------------|
| Upload | `upload` | Upload a binary audio file to AssemblyAI |
| Create | `create` | Create a new transcript from an audio URL |
| Get | `get` | Get a transcript by ID |
| List | `list` | List all transcripts |
| Delete | `delete` | Delete a transcript by ID |
| Get Paragraphs | `getParagraphs` | Get transcript split into paragraphs |
| Get Sentences | `getSentences` | Get transcript split into sentences |
| Get Subtitles | `getSubtitles` | Export transcript as SRT or VTT subtitles |
| Get Redacted Audio | `getRedactedAudio` | Download the redacted version of the audio |
| Word Search | `wordSearch` | Search for words in a transcript |
| Chat Completions | `chatCompletions` | Send chat messages through the LLM gateway |
| Understanding | `understanding` | Use the understanding endpoint for audio analysis |

### Parameters

#### File: Upload

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Binary Property | `string` | No | `data` | Name of the binary property containing the audio file to upload. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. Supports expressions. |

#### Transcript: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Audio URL | `string` | Yes | — | URL of the audio file to transcribe. Can be a public URL or an AssemblyAI upload URL. Supports expressions. |
| Wait for Completion | `boolean` | No | `true` | Whether to poll and wait until the transcript is completed before returning. |
| Polling Interval (ms) | `number` | No | `3000` | Milliseconds between polling attempts when waiting for transcript completion. _(shown when Wait for Completion is `true`)_ |
| Max Polling Attempts | `number` | No | `60` | Maximum number of polling attempts before timing out. _(shown when Wait for Completion is `true`)_ |
| Transcript Options | `collection` | No | `{}` | Additional options for transcript creation. |
| — Speech Model | `options` | No | `best` | The speech recognition model to use. |
| | | | | Options: `best` (highest accuracy model), `nano` (faster, lower-cost model) |
| — Language Code | `string` | No | `en` | The language code of the audio (e.g., en, es, fr, de). |
| — Language Detection | `boolean` | No | `false` | Whether to automatically detect the language of the audio. |
| — Speaker Labels | `boolean` | No | `false` | Whether to enable speaker diarization. |
| — Speakers Expected | `number` | No | `0` | Expected number of speakers. Set to 0 for automatic detection. |
| — Punctuate | `boolean` | No | `true` | Whether to add punctuation to the transcript. |
| — Format Text | `boolean` | No | `true` | Whether to format text (e.g., numbers, dates). |
| — Sentiment Analysis | `boolean` | No | `false` | Whether to enable sentiment analysis on each sentence. |
| — Entity Detection | `boolean` | No | `false` | Whether to detect entities (people, places, organizations, etc.). |
| — Auto Chapters | `boolean` | No | `false` | Whether to automatically generate chapters with summaries. |
| — Auto Highlights | `boolean` | No | `false` | Whether to automatically detect key phrases and highlights. |
| — Content Safety | `boolean` | No | `false` | Whether to detect sensitive content topics. |
| — Redact PII | `boolean` | No | `false` | Whether to redact personally identifiable information from the transcript. |
| — Redact PII Policies | `string` | No | — | Comma-separated PII policies to redact (e.g., medical_process, phone_number, email_address, credit_card_number, ssn, date_of_birth, person_name). |
| — Summarization | `boolean` | No | `false` | Whether to generate a summary of the transcript. |
| — Summary Model | `options` | No | `informative` | The summarization model to use. |
| | | | | Options: `informative` (best for informational content), `conversational` (best for conversational audio), `catchy` (best for catchy, engaging summaries) |
| — Summary Type | `options` | No | `bullets` | The type of summary to generate. |
| | | | | Options: `bullets` (concise bullet points), `bullets_verbose` (detailed bullet points), `gist` (brief one-line summary), `headline` (headline-style summary), `paragraph` (full paragraph summary) |
| — Webhook URL | `string` | No | — | URL to receive a webhook notification when transcription is complete. |
| — Webhook Auth Header Name | `string` | No | — | Name of the authentication header for the webhook. |
| — Webhook Auth Header Value | `string` | No | — | Value of the authentication header for the webhook. |
| — Dual Channel | `boolean` | No | `false` | Whether the audio is dual-channel (stereo) with separate speakers per channel. |
| — Filter Profanity | `boolean` | No | `false` | Whether to filter profanity from the transcript text. |
| — Word Boost | `string` | No | — | Comma-separated words or phrases to boost recognition accuracy for. |

#### Transcript: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |

#### Transcript: List

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all transcripts using cursor pagination. |
| Limit | `number` | No | `20` | Maximum number of transcripts to return. _(shown when Return All is `false`)_ |

#### Transcript: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |

#### Transcript: Get Paragraphs

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |

#### Transcript: Get Sentences

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |

#### Transcript: Get Subtitles

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |
| Subtitle Format | `options` | No | `srt` | The subtitle format to export. |
| | | | | Options: `srt`, `vtt` |

#### Transcript: Get Redacted Audio

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |
| Output Binary Property | `string` | No | `data` | Name of the binary property to store the redacted audio file. |
| Output Filename | `string` | No | `redacted_audio.wav` | Filename for the downloaded redacted audio file. |

#### Transcript: Word Search

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Transcript ID | `string` | Yes | — | The ID of the transcript. Supports expressions. |
| Search Words | `string` | Yes | — | Comma-separated list of words to search for in the transcript. Supports expressions. |

#### LLM Gateway: Chat Completions

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Chat Messages | `string` | No | — | JSON array of chat messages (e.g., [{"role": "user", "content": "Summarize this transcript"}]). Supports expressions. |
| Chat Model | `string` | No | `anthropic/claude-3-5-sonnet` | The LLM model to use for chat completions (e.g., anthropic/claude-3-5-sonnet). |
| Transcript IDs | `string` | No | — | Comma-separated transcript IDs to provide as context for the LLM chat. Supports expressions. |

#### LLM Gateway: Understanding

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Understanding Input | `string` | No | — | JSON input for the understanding endpoint. Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The AssemblyAI response is merged into the item JSON **at the top level** — its fields sit alongside the fields already on the item, and any field of the same name is overwritten. Binary data from the input item is forwarded unchanged; Get Redacted Audio additionally attaches the downloaded audio as a new binary property.

| Operation | What lands on the item |
|-----------|------------------------|
| Upload | The upload response, including the `upload_url` you hand to Create. |
| Create | The transcript object — `id`, `status`, the full transcript text with word timestamps, and whichever intelligence results you enabled (speaker labels, sentiment scores, detected entities, chapters, highlights, content safety, summary). With Wait for Completion off the node returns immediately and `status` is still `queued` or `processing`. |
| Get | The same transcript object, fetched by ID. |
| List | `transcripts` (the array of transcript records) plus the API's own pagination details. With Return All on, every page is fetched and the item carries `transcripts` and `total_count` instead. |
| Delete | The deletion response for that transcript. |
| Get Paragraphs | The transcript split into paragraphs, as returned by AssemblyAI. |
| Get Sentences | The transcript split into sentences, as returned by AssemblyAI. |
| Get Subtitles | `text` — the whole SRT or VTT document as a single string — and `format` (`srt` or `vtt`). |
| Get Redacted Audio | `redacted_audio_url` and `status`, plus the downloaded audio file stored under the Output Binary Property. |
| Word Search | The word-search response for the words you supplied. |
| Chat Completions | The LLM gateway chat response. |
| Understanding | The understanding endpoint response. |

Reference the result downstream by expression, e.g. `{{ $json.upload_url }}` after Upload or `{{ $json.id }}` after Create.

## Usage Examples

- Transcribe an audio file from a URL with speaker labels
- Upload binary audio data and get a transcription URL
- Get transcript paragraphs and sentences for formatting
- Export subtitles in SRT or VTT format
- Download redacted audio with PII removed
- Search for specific words in a transcript
- Use LLM gateway for chat completions with transcript context
- Analyze audio for sentiment, entities, and content safety

## Example Configuration

Upload an audio file:

```json
{
  "resource": "file",
  "operation": "upload",
  "binaryPropertyName": "data",
  "maxConcurrency": 5
}
```

Create a transcript without waiting for it to finish:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://example.com/audio/interview.mp3",
  "waitForCompletion": false,
  "maxConcurrency": 5
}
```

Create a transcript and wait for the result:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://example.com/audio/interview.mp3",
  "waitForCompletion": true,
  "pollingInterval": 3000,
  "maxPollingAttempts": 60,
  "maxConcurrency": 5
}
```

Create a transcript with advanced options:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://storage.example.com/podcast.mp3",
  "waitForCompletion": true,
  "pollingInterval": 5000,
  "maxPollingAttempts": 30,
  "transcriptOptions": {
    "speech_model": "best",
    "language_code": "en",
    "language_detection": false,
    "speaker_labels": true,
    "speakers_expected": 2,
    "punctuate": true,
    "format_text": true,
    "sentiment_analysis": false,
    "entity_detection": true,
    "auto_chapters": false,
    "auto_highlights": true,
    "content_safety": false,
    "redact_pii": false,
    "redact_pii_policies": "",
    "summarization": false,
    "summary_model": "informative",
    "summary_type": "bullets",
    "webhook_url": "",
    "webhook_auth_header_name": "",
    "webhook_auth_header_value": "",
    "dual_channel": false,
    "filter_profanity": false,
    "word_boost": ""
  },
  "maxConcurrency": 5
}
```

Create a transcript with PII redaction and summarization:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://cdn.example.com/call-recording.wav",
  "waitForCompletion": true,
  "pollingInterval": 4000,
  "maxPollingAttempts": 50,
  "transcriptOptions": {
    "speech_model": "best",
    "language_code": "en",
    "language_detection": false,
    "speaker_labels": false,
    "speakers_expected": 0,
    "punctuate": true,
    "format_text": true,
    "sentiment_analysis": true,
    "entity_detection": false,
    "auto_chapters": false,
    "auto_highlights": false,
    "content_safety": false,
    "redact_pii": true,
    "redact_pii_policies": "person_name,phone_number,email_address",
    "summarization": true,
    "summary_model": "informative",
    "summary_type": "bullets",
    "webhook_url": "",
    "webhook_auth_header_name": "",
    "webhook_auth_header_value": "",
    "dual_channel": false,
    "filter_profanity": true,
    "word_boost": ""
  },
  "maxConcurrency": 3
}
```

Get a transcript by ID:

```json
{
  "resource": "transcript",
  "operation": "get",
  "transcriptId": "abc123xyz",
  "maxConcurrency": 5
}
```

Delete a transcript:

```json
{
  "resource": "transcript",
  "operation": "delete",
  "transcriptId": "abc123xyz",
  "maxConcurrency": 5
}
```

Get paragraphs:

```json
{
  "resource": "transcript",
  "operation": "getParagraphs",
  "transcriptId": "abc123xyz",
  "maxConcurrency": 5
}
```

Get sentences:

```json
{
  "resource": "transcript",
  "operation": "getSentences",
  "transcriptId": "abc123xyz",
  "maxConcurrency": 5
}
```

Export subtitles as SRT:

```json
{
  "resource": "transcript",
  "operation": "getSubtitles",
  "transcriptId": "abc123xyz",
  "subtitleFormat": "srt",
  "maxConcurrency": 5
}
```

Export subtitles as VTT:

```json
{
  "resource": "transcript",
  "operation": "getSubtitles",
  "transcriptId": "abc123xyz",
  "subtitleFormat": "vtt",
  "maxConcurrency": 5
}
```

Download redacted audio:

```json
{
  "resource": "transcript",
  "operation": "getRedactedAudio",
  "transcriptId": "abc123xyz",
  "outputBinaryPropertyName": "redactedAudio",
  "outputFilename": "redacted_output.mp3",
  "maxConcurrency": 5
}
```

Search a transcript for words:

```json
{
  "resource": "transcript",
  "operation": "wordSearch",
  "transcriptId": "abc123xyz",
  "searchWords": "contract,payment,deadline",
  "maxConcurrency": 5
}
```

List transcripts up to a limit:

```json
{
  "resource": "transcript",
  "operation": "list",
  "returnAll": false,
  "limit": 25,
  "maxConcurrency": 5
}
```

List every transcript, paginating automatically:

```json
{
  "resource": "transcript",
  "operation": "list",
  "returnAll": true,
  "maxConcurrency": 5
}
```

Leave `limit` out when Return All is on — it only applies when Return All is off.

Send chat messages through the LLM gateway with transcript context:

```json
{
  "resource": "llmGateway",
  "operation": "chatCompletions",
  "chatMessages": "[{\"role\": \"user\", \"content\": \"Summarize the key decisions from this meeting transcript.\"}]",
  "chatModel": "anthropic/claude-3-5-sonnet",
  "chatTranscriptIds": "abc123xyz,def456uvw",
  "maxConcurrency": 5
}
```

Send chat messages without transcript context:

```json
{
  "resource": "llmGateway",
  "operation": "chatCompletions",
  "chatMessages": "[{\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}, {\"role\": \"user\", \"content\": \"What are best practices for meeting notes?\"}]",
  "chatModel": "openai/gpt-4o",
  "chatTranscriptIds": "",
  "maxConcurrency": 5
}
```

Call the understanding endpoint:

```json
{
  "resource": "llmGateway",
  "operation": "understanding",
  "understandingInput": "{\"audio_url\": \"https://example.com/audio.mp3\", \"questions\": [{\"question\": \"What is the main topic?\", \"answer_format\": \"brief\"}]}",
  "maxConcurrency": 5
}
```

### Upload, then transcribe (two nodes)

Upload a local binary audio file first, then use the returned upload URL to create the transcript.

Step 1 — upload node:

```json
{
  "resource": "file",
  "operation": "upload",
  "binaryPropertyName": "data",
  "maxConcurrency": 5
}
```

Step 2 — create transcript node, reading `upload_url` from step 1:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "={{$json.upload_url}}",
  "waitForCompletion": true,
  "pollingInterval": 3000,
  "maxPollingAttempts": 60,
  "transcriptOptions": {
    "speech_model": "best",
    "language_code": "en",
    "language_detection": false,
    "speaker_labels": false,
    "speakers_expected": 0,
    "punctuate": true,
    "format_text": true,
    "sentiment_analysis": false,
    "entity_detection": false,
    "auto_chapters": false,
    "auto_highlights": false,
    "content_safety": false,
    "redact_pii": false,
    "redact_pii_policies": "",
    "summarization": false,
    "summary_model": "informative",
    "summary_type": "bullets",
    "webhook_url": "",
    "webhook_auth_header_name": "",
    "webhook_auth_header_value": "",
    "dual_channel": false,
    "filter_profanity": false,
    "word_boost": ""
  },
  "maxConcurrency": 5
}
```

### Transcribe a public URL with speaker labels

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://cdn.example.com/webinar-recording.mp4",
  "waitForCompletion": true,
  "pollingInterval": 5000,
  "maxPollingAttempts": 120,
  "transcriptOptions": {
    "speech_model": "best",
    "language_code": "en",
    "language_detection": false,
    "speaker_labels": true,
    "speakers_expected": 3,
    "punctuate": true,
    "format_text": true,
    "sentiment_analysis": false,
    "entity_detection": false,
    "auto_chapters": true,
    "auto_highlights": false,
    "content_safety": false,
    "redact_pii": false,
    "redact_pii_policies": "",
    "summarization": true,
    "summary_model": "informative",
    "summary_type": "bullets",
    "webhook_url": "",
    "webhook_auth_header_name": "",
    "webhook_auth_header_value": "",
    "dual_channel": false,
    "filter_profanity": false,
    "word_boost": "Q3,roadmap,milestone"
  },
  "maxConcurrency": 3
}
```

### Transcribe, redact PII, then download the redacted audio

Step 1 — create the redacted transcript:

```json
{
  "resource": "transcript",
  "operation": "create",
  "audioUrl": "https://example.com/sensitive-call.mp3",
  "waitForCompletion": true,
  "pollingInterval": 4000,
  "maxPollingAttempts": 60,
  "transcriptOptions": {
    "speech_model": "best",
    "language_code": "en",
    "language_detection": false,
    "speaker_labels": false,
    "speakers_expected": 0,
    "punctuate": true,
    "format_text": true,
    "sentiment_analysis": false,
    "entity_detection": false,
    "auto_chapters": false,
    "auto_highlights": false,
    "content_safety": false,
    "redact_pii": true,
    "redact_pii_policies": "person_name,phone_number,email_address,ssn",
    "summarization": false,
    "summary_model": "informative",
    "summary_type": "bullets",
    "webhook_url": "",
    "webhook_auth_header_name": "",
    "webhook_auth_header_value": "",
    "dual_channel": false,
    "filter_profanity": false,
    "word_boost": ""
  },
  "maxConcurrency": 5
}
```

Step 2 — download the redacted audio:

```json
{
  "resource": "transcript",
  "operation": "getRedactedAudio",
  "transcriptId": "={{$json.id}}",
  "outputBinaryPropertyName": "redactedAudio",
  "outputFilename": "redacted_call.mp3",
  "maxConcurrency": 5
}
```

### Analyze a transcript with the LLM gateway

Step 1 — get the transcript:

```json
{
  "resource": "transcript",
  "operation": "get",
  "transcriptId": "abc123xyz",
  "maxConcurrency": 5
}
```

Step 2 — chat completions using that transcript as context:

```json
{
  "resource": "llmGateway",
  "operation": "chatCompletions",
  "chatMessages": "[{\"role\": \"user\", \"content\": \"Extract all action items and assigned owners from this transcript.\"}]",
  "chatModel": "anthropic/claude-3-5-sonnet",
  "chatTranscriptIds": "abc123xyz",
  "maxConcurrency": 5
}
```

### Search for keywords across a transcript

```json
{
  "resource": "transcript",
  "operation": "wordSearch",
  "transcriptId": "abc123xyz",
  "searchWords": "budget,approval,Q4,launch",
  "maxConcurrency": 5
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

AssemblyAI transcribes audio via speech-to-text and applies intelligence features including sentiment analysis, entity detection, PII redaction, content safety, and auto-chapter generation. Use it when a workflow needs to convert audio recordings into structured text or extract insights like sentiment, named entities, or topic summaries from spoken content. It outputs a transcript with full text, word timestamps, paragraph and sentence segments, detected entities, sentiment scores, and optional SRT or VTT subtitle files.

### Key Rules and Gotchas

1. **`transcriptOptions` is a flat collection object.** Never wrap it in `_default` or an array. All sub-fields sit directly under the `transcriptOptions` key.

2. **`waitForCompletion` defaults to `true`, so `create` blocks while it polls.** A long recording can hold the node open for `pollingInterval × maxPollingAttempts` (3 minutes at the defaults of `3000` ms × `60`). Set `waitForCompletion: false` for fire-and-forget creates, and raise `maxPollingAttempts` for long audio. **`pollingInterval` and `maxPollingAttempts` only apply when `waitForCompletion` is `true` and `operation` is `"create"`** — do not include them in other contexts.

3. **`limit` is only valid when `returnAll` is `false` on the `list` operation.** When `returnAll` is `true`, omit `limit`.

4. **`chatMessages` must be a JSON-serialized string**, not a raw JSON object. Escape inner quotes appropriately.

5. **`transcriptId` is shared across multiple operations** (`get`, `delete`, `getParagraphs`, `getSentences`, `getSubtitles`, `getRedactedAudio`, `wordSearch`) — always required for single-transcript operations other than `create`.

6. **`resource` and `operation` must be consistent.** For example, `"upload"` belongs to `resource: "file"`, transcript CRUD operations belong to `resource: "transcript"`, and `"chatCompletions"` / `"understanding"` belong to `resource: "llmGateway"`.