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

# Speaker Diarization

> Identify who spoke and when — returns anonymous speaker labels with timestamps.

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

Segment audio or video by speaker using **pyannote**. Returns timestamped speaker turns labeled `SPEAKER_00`, `SPEAKER_01`, etc. — anonymous labels based on voice characteristics, not identity.

**Need named speakers?** Use [Multimodal Speaker Recognition](/visual-intelligence/transcript/speaker-recognition), which combines voice + face recognition to identify speakers by name.

<Note>
  **Pricing:** \$0.001/second of audio or video
</Note>

## Endpoints

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

Use **sync** for short clips. Use **async** for long files.

<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).
</Warning>

### Request Body

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| asset\_id | string | Yes      | The uploaded audio or video asset ID |

### Code Examples

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

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

  ```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 diarize_sync(asset_id: str):
      return requests.post(f"{BASE_URL}/sync-generate-speaker",
          json={"asset_id": asset_id}, headers=HEADERS).json()

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

## Sync Response

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "model": "pyannote",
      "items": [
        { "start": 0.03, "end": 0.13, "speaker": "SPEAKER_01" },
        { "start": 0.13, "end": 13.40, "speaker": "SPEAKER_00" }
      ]
    },
    "failed": false,
    "success": true
  }
  ```
</ResponseExample>

### Sync Response Parameters

| Parameter             | Type   | Description                                  |
| --------------------- | ------ | -------------------------------------------- |
| data.model            | string | Model used (e.g., `pyannote`)                |
| data.items            | array  | Speaker segments                             |
| data.items\[].start   | number | Segment start time in seconds                |
| data.items\[].end     | number | Segment end time in seconds                  |
| data.items\[].speaker | string | Anonymous speaker label (e.g., `SPEAKER_00`) |

## Async Response

<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": 0.44, "end": 1.68, "speaker": "SPEAKER_06" },
          { "start": 13.80, "end": 20.75, "speaker": "SPEAKER_00" }
        ],
        "usage_metadata": {
          "duration": 20.75,
          "model": "pyannote",
          "output_tokens": 0,
          "prompt_tokens": 0
        }
      },
      "msg": "Speech diarization completed successfully",
      "success": true
    },
    "task_id": "0d2d50fbdd0c4597a6a45c0359a42d76"
  }
  ```
</ResponseExample>

### Callback Response Parameters

| Parameter                          | Type   | Description                           |
| ---------------------------------- | ------ | ------------------------------------- |
| data.data.data                     | array  | Speaker segments                      |
| data.data.data\[].start            | number | Segment start time in seconds         |
| data.data.data\[].end              | number | Segment end time in seconds           |
| data.data.data\[].speaker          | string | Anonymous speaker label               |
| data.data.usage\_metadata.duration | number | Total audio duration in seconds       |
| data.data.usage\_metadata.model    | string | Model used                            |
| task\_id                           | string | Task ID matching the initial response |