> ## 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.

# Whisper Audio Transcription

> Transcribe audio or video files using OpenAI Whisper, with optional speaker labeling.

<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>

Transcribe speech from audio or video files using **OpenAI Whisper**. Returns timestamped text segments. Add `speaker: true` to label each segment by speaker (doubles the price).

Use this endpoint when you need fast, cost-effective speech-to-text on your own uploaded assets. For third-party providers with richer features (word-level confidence, entity detection, PII redaction), see [ElevenLabs](/visual-intelligence/transcript/elevenlabs) or [AssemblyAI](/visual-intelligence/transcript/assemblyai).

<Note>
  **Pricing:**

  * \$0.001/second (without speaker labeling)
  * \$0.002/second (with `speaker: true`)
</Note>

## Endpoints

| Method | Endpoint                               | Returns                      |
| ------ | -------------------------------------- | ---------------------------- |
| `POST` | `/transcriptions/sync-generate-audio`  | Result directly              |
| `POST` | `/transcriptions/async-generate-audio` | `task_id` + webhook callback |

Use **sync** for short clips where you want an immediate result. Use **async** for long files — you'll receive the result via webhook when processing completes.

<Warning>
  The async endpoint requires a configured webhook URL. See [Webhooks Settings](https://api-platform.memories.ai/webhooks) and the [Webhooks Guide](/visual-intelligence/getting-started/webhooks).

  Without a configured webhook the async endpoint rejects requests with:

  ```json theme={null}
  HTTP 400 {"code": 400, "msg": "An async request requires at least one webhook.", "data": null}
  ```
</Warning>

### Error Responses

Verified live against the sync and async endpoints:

```json theme={null}
// Sync — missing asset_id
HTTP 400 {"code": 400, "msg": "asset_id cannot be null or empty", "data": null}

// Sync / async — unknown asset_id (and many other validation failures)
HTTP 400 {"code": 400, "msg": "Request has exceeded the limit.", "data": null}
```

<Note>
  The string `"Request has exceeded the limit."` is shared across **multiple** failure paths on this endpoint — true rate-limit rejections AND validation failures (unknown `asset_id`, wrong model, etc.). Branch on `HTTP 400` only, don't try to parse `msg` to discriminate.
</Note>

## Supported Models

* `whisper-1`

### Request Body

| Parameter | Type    | Required | Description                                                                                                              |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| asset\_id | string  | Yes      | The uploaded audio or video asset ID to transcribe                                                                       |
| model     | string  | No       | Transcription model (default: `whisper-1`)                                                                               |
| speaker   | boolean | No       | Enable speaker labeling. Each segment will include `speaker` (e.g., `SPEAKER_00`). Doubles the price (default: `false`). |

### Code Examples

<CodeGroup>
  ```bash Sync (cURL) theme={null}
  curl --request POST \
    --url https://mavi-backend.memories.ai/serve/api/v2/transcriptions/sync-generate-audio \
    --header 'Authorization: sk-mavi-...' \
    --header 'Content-Type: application/json' \
    --data '{
      "asset_id": "re_657929111888723968",
      "model": "whisper-1",
      "speaker": false
    }'
  ```

  ```bash Async (cURL) theme={null}
  curl --request POST \
    --url https://mavi-backend.memories.ai/serve/api/v2/transcriptions/async-generate-audio \
    --header 'Authorization: sk-mavi-...' \
    --header 'Content-Type: application/json' \
    --data '{
      "asset_id": "re_657929111888723968",
      "model": "whisper-1",
      "speaker": true
    }'
  ```

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

  BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2/transcriptions"
  HEADERS = {"Authorization": "sk-mavi-..."}

  # Sync — result returned immediately
  def transcribe_sync(asset_id: str, speaker: bool = False):
      return requests.post(f"{BASE_URL}/sync-generate-audio", json={
          "asset_id": asset_id, "model": "whisper-1", "speaker": speaker
      }, headers=HEADERS).json()

  # Async — returns task_id; result delivered to webhook
  def transcribe_async(asset_id: str, speaker: bool = False):
      return requests.post(f"{BASE_URL}/async-generate-audio", json={
          "asset_id": asset_id, "model": "whisper-1", "speaker": speaker
      }, headers=HEADERS).json()
  ```
</CodeGroup>

## Sync Response

<ResponseExample>
  ```json Without speaker theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "model": "whisper-1",
      "items": [
        { "text": "Hello, how are you today?", "start_time": 0.0, "end_time": 2.98 },
        { "text": "I'm doing well, thank you.", "start_time": 2.98, "end_time": 6.78 }
      ]
    },
    "failed": false,
    "success": true
  }
  ```

  ```json With speaker=true theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "model": "whisper-1",
      "items": [
        { "text": "Hello, how are you today?", "speaker": "SPEAKER_00", "start_time": 0.0, "end_time": 2.98 },
        { "text": "I'm doing well, thank you.", "speaker": "SPEAKER_01", "start_time": 2.98, "end_time": 6.78 }
      ]
    },
    "failed": false,
    "success": true
  }
  ```
</ResponseExample>

### Sync Response Parameters

| Parameter                 | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| data.model                | string | Model used (e.g., `whisper-1`)                                        |
| data.items                | array  | Transcription segments                                                |
| data.items\[].text        | string | Transcribed text for this segment                                     |
| data.items\[].start\_time | number | Segment start time in seconds                                         |
| data.items\[].end\_time   | number | Segment end time in seconds                                           |
| data.items\[].speaker     | string | Speaker label (e.g., `SPEAKER_00`). Only present when `speaker=true`. |

## Async Response

The initial response returns a `task_id`. Results are delivered to your webhook URL when transcription completes.

<ResponseExample>
  ```json Initial response theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": { "task_id": "ec2449885ba84c4f943a80ff0633158e" },
    "failed": false,
    "success": true
  }
  ```

  ```json Webhook callback theme={null}
  {
    "code": 200,
    "message": "SUCCESS",
    "data": {
      "data": {
        "data": [
          { "start_time": 0.0, "end_time": 2.0, "text": " Oh", "speaker": null }
        ],
        "usage_metadata": {
          "duration": 2,
          "model": "whisper-1",
          "output_tokens": 0,
          "prompt_tokens": 0
        }
      },
      "msg": "ASR transcription completed successfully",
      "success": true
    },
    "task_id": "016c7052f8224d5c971e35b7d08972fc"
  }
  ```
</ResponseExample>

### Callback Response Parameters

| Parameter                          | Type           | Description                                 |
| ---------------------------------- | -------------- | ------------------------------------------- |
| data.data.data                     | array          | Transcription segments                      |
| data.data.data\[].start\_time      | number         | Segment start time in seconds               |
| data.data.data\[].end\_time        | number         | Segment end time in seconds                 |
| data.data.data\[].text             | string         | Transcribed text                            |
| data.data.data\[].speaker          | string \| null | Speaker label, or `null` if `speaker=false` |
| data.data.usage\_metadata.duration | number         | Audio duration in seconds                   |
| data.data.usage\_metadata.model    | string         | Model used                                  |
| task\_id                           | string         | Task ID matching the initial response       |