> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AssemblyAI

> Transcribe audio to text using AssemblyAI Universal-2 model.

<Info>
  **Product**: Visual Intelligence — Audio File Transcription
  **Use case**: Transcribe an uploaded audio/video **file** to text — async batch or sync, multiple providers (Whisper, ElevenLabs, AssemblyAI) with optional speaker labels. For live streams, see Live Audio Transcription.
  **Host**: `https://mavi-backend.memories.ai/serve/api/v2`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

Uses **AssemblyAI Universal-2** model. Submits a job and polls until completion, then returns the full result.

<Note>
  **Pricing:** \$0.15/hour of audio, billed by actual audio duration (in seconds).
</Note>

## Audio Source

You must provide **one** of the following (priority: `asset_id` > `url` > `source_url`).

## Parameters

<ParamField header="Authorization" type="string" required>
  API key for authentication (e.g. `sk-mavi-...`).
</ParamField>

<ParamField body="provider" type="string" required>
  STT provider. Must be `assemblyai`.
</ParamField>

<ParamField body="asset_id" type="string">
  The unique identifier of an uploaded audio/video asset (e.g. `re_xxx`). Resolved to a signed GCS URL.
</ParamField>

<ParamField body="url" type="string">
  A publicly accessible audio URL.
</ParamField>

<ParamField body="source_url" type="string">
  A `gs://` GCS path or public HTTP URL. GCS paths are converted to signed URLs automatically.
</ParamField>

<ParamField body="language_code" type="string">
  Language code (ISO 639-1, e.g. `en`, `zh`). If omitted, the provider auto-detects the language.
</ParamField>

<ParamField body="punctuate" type="boolean" default="true">
  Add punctuation.
</ParamField>

<ParamField body="format_text" type="boolean" default="true">
  Format numbers, dates, etc.
</ParamField>

<ParamField body="speaker_labels" type="boolean">
  Enable speaker diarization.
</ParamField>

<ParamField body="speakers_expected" type="integer">
  Expected number of speakers.
</ParamField>

<ParamField body="language_detection" type="boolean">
  Enable automatic language detection.
</ParamField>

<ParamField body="language_confidence_threshold" type="number">
  Confidence threshold for language detection (0.0–1.0).
</ParamField>

<ParamField body="speech_model" type="string">
  Speech recognition model to use.
</ParamField>

<ParamField body="speech_threshold" type="number">
  Speech confidence threshold (0.0–1.0).
</ParamField>

<ParamField body="disfluencies" type="boolean">
  Include disfluencies (um, uh, etc.).
</ParamField>

<ParamField body="sentiment_analysis" type="boolean">
  Enable sentiment analysis per utterance.
</ParamField>

<ParamField body="entity_detection" type="boolean">
  Enable entity detection (names, locations, etc.).
</ParamField>

<ParamField body="auto_highlights" type="boolean">
  Automatically highlight key phrases.
</ParamField>

<ParamField body="content_safety" type="boolean">
  Enable content safety detection.
</ParamField>

<ParamField body="iab_categories" type="boolean">
  Enable IAB topic categorization.
</ParamField>

<ParamField body="auto_chapters" type="boolean">
  Automatically generate chapters.
</ParamField>

<ParamField body="summarization" type="boolean">
  Enable summarization.
</ParamField>

<ParamField body="summary_model" type="string">
  Summarization model: `informative` or `conversational`.
</ParamField>

<ParamField body="summary_type" type="string">
  Summary format: `bullets`, `bullets_verbose`, `headline`, `paragraph`, or `gist`.
</ParamField>

<ParamField body="redact_pii" type="boolean">
  Enable PII redaction.
</ParamField>

<ParamField body="redact_pii_policies" type="string[]">
  PII types to redact (e.g. `email_address`, `phone_number`, `person_name`).
</ParamField>

<ParamField body="redact_pii_sub" type="string">
  PII replacement strategy: `hash` or `entity_name`.
</ParamField>

<ParamField body="redact_pii_audio" type="boolean">
  Redact PII from audio output.
</ParamField>

<ParamField body="redact_pii_audio_quality" type="string">
  Redacted audio quality: `mp3` or `wav`.
</ParamField>

<ParamField body="filter_profanity" type="boolean">
  Filter profanity from transcript.
</ParamField>

<ParamField body="word_boost" type="string[]">
  List of words to boost recognition.
</ParamField>

<ParamField body="boost_param" type="string">
  Boost strength: `low`, `default`, or `high`.
</ParamField>

<ParamField body="custom_spelling" type="object[]">
  Custom spelling corrections.
</ParamField>

<ParamField body="webhook_url" type="string">
  AssemblyAI webhook callback URL.
</ParamField>

<ParamField body="multichannel" type="boolean">
  Enable multi-channel transcription.
</ParamField>

<ParamField body="audio_start_from" type="integer">
  Start transcription from this time (milliseconds).
</ParamField>

<ParamField body="audio_end_at" type="integer">
  End transcription at this time (milliseconds).
</ParamField>

<ParamField body="custom_topics" type="boolean">
  Enable custom topic detection.
</ParamField>

<ParamField body="topics" type="string[]">
  Custom topic labels.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://mavi-backend.memories.ai/serve/api/v2/transcriptions/speech-to-text \
    --header 'Authorization: sk-mavi-...' \
    --header 'Content-Type: application/json' \
    --data '{
      "provider": "assemblyai",
      "asset_id": "re_657929111888723968",
      "language_code": "en",
      "speaker_labels": true,
      "speakers_expected": 2,
      "punctuate": true,
      "format_text": true
    }'
  ```

  ```javascript fetch theme={null}
  const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2/transcriptions";
  const API_KEY = "sk-mavi-...";

  const response = await fetch(`${BASE_URL}/speech-to-text`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': API_KEY
    },
    body: JSON.stringify({
      provider: 'assemblyai',
      asset_id: 're_657929111888723968',
      language_code: 'en',
      speaker_labels: true,
      speakers_expected: 2,
      punctuate: true,
      format_text: true
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2/transcriptions"
  API_KEY = "sk-mavi-..."
  HEADERS = {
      "Authorization": API_KEY,
      "Content-Type": "application/json"
  }

  response = requests.post(f"{BASE_URL}/speech-to-text", json={
      "provider": "assemblyai",
      "asset_id": "re_657929111888723968",
      "language_code": "en",
      "speaker_labels": True,
      "speakers_expected": 2,
      "punctuate": True,
      "format_text": True
  }, headers=HEADERS)

  print(response.json())
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "id": "9a27d0d5-d2db-448c-823c-f098507789be",
      "status": "completed",
      "language_code": "en_us",
      "audio_url": "https://storage.googleapis.com/...",
      "audio_duration": 52,
      "text": "Hello, how are you today? I'm doing well, thank you.",
      "words": [
        {
          "text": "Hello,",
          "start": 0,
          "end": 520,
          "confidence": 0.99,
          "speaker": "A"
        },
        {
          "text": "how",
          "start": 520,
          "end": 780,
          "confidence": 0.98,
          "speaker": "A"
        }
      ],
      "utterances": [
        {
          "confidence": 0.97,
          "start": 0,
          "end": 2980,
          "text": "Hello, how are you today?",
          "speaker": "A"
        },
        {
          "confidence": 0.95,
          "start": 2980,
          "end": 5200,
          "text": "I'm doing well, thank you.",
          "speaker": "B"
        }
      ],
      "confidence": 0.97,
      "punctuate": true,
      "format_text": true,
      "speaker_labels": true,
      "speakers_expected": 2
    },
    "failed": false,
    "success": true
  }
  ```
</ResponseExample>

### Response Parameters

| Parameter                     | Type           | Description                                                             |
| ----------------------------- | -------------- | ----------------------------------------------------------------------- |
| data.id                       | string         | AssemblyAI transcript ID                                                |
| data.status                   | string         | Transcript status: `completed`                                          |
| data.language\_code           | string         | Detected language code                                                  |
| data.audio\_duration          | integer        | Audio duration in seconds                                               |
| data.text                     | string         | Full transcription text                                                 |
| data.confidence               | number         | Overall transcription confidence (0.0–1.0)                              |
| data.words                    | array\[object] | Word-level transcription with timing (milliseconds)                     |
| data.words\[].text            | string         | The transcribed word                                                    |
| data.words\[].start           | integer        | Start time in milliseconds                                              |
| data.words\[].end             | integer        | End time in milliseconds                                                |
| data.words\[].confidence      | number         | Word confidence score                                                   |
| data.words\[].speaker         | string         | Speaker label (e.g. `A`, `B`). Only present when `speaker_labels=true`. |
| data.utterances               | array\[object] | Sentence-level segments (only when `speaker_labels=true`)               |
| data.utterances\[].text       | string         | Utterance text                                                          |
| data.utterances\[].start      | integer        | Start time in milliseconds                                              |
| data.utterances\[].end        | integer        | End time in milliseconds                                                |
| data.utterances\[].confidence | number         | Utterance confidence score                                              |
| data.utterances\[].speaker    | string         | Speaker label                                                           |

<Note>
  **Timestamps** are in **milliseconds** (e.g. `520`).
</Note>