Name: meronym Speaker Diarization and Transcription API
Brand: magicapi
SKU: api-magicapi-whisper-speaker-diarization-meronym-speaker-transcription
Availability: InStock
Author: API Market

Shashank Agarwal

# 🗣️ Speaker Diarization and Transcription API (meronym Speaker Transcription)

## Overview
Speaker Transcription, published by meronym, combines Whisper speech recognition with speaker diarization. It transcribes an audio file and labels which speaker said each part.

Send an `audio` URL and the API returns the URL of a JSON file. The file lists segments, each with a speaker label (`A`, `B`, ...), start and stop times and the transcribed text with timestamps, plus the number of speakers and one embedding vector per speaker. An optional `prompt` is passed to every Whisper call, which helps with names and terms.

## Features
- **Transcription with speakers**: every segment carries a speaker label and its text.
- **Timestamps**: segment `start` and `stop` times and a `start` time for each line of text, in `H:MM:SS.ffffff` format.
- **Speaker count and labels**: `speakers.count` and `speakers.labels` give the number of detected speakers.
- **Speaker embeddings**: one embedding vector per speaker in `speakers.embeddings`, useful for matching voices across files.
- **Prompt**: optional `prompt` text is passed to each Whisper call, for example to spell names or jargon correctly.

## Use Cases
1. **Meeting and interview notes**: produce transcripts that show who said what.
2. **Podcast transcripts**: split an episode by host and guest with timestamps for show notes.
3. **Call review**: separate agent and customer speech in recorded calls.
4. **Speaker search**: compare the speaker embeddings from different recordings to find the same voice.

## Visual Examples
### Example Input
A short English recording with two different voices.

[Listen to the example input](https://blog.api.market/wp-content/uploads/2026/10/speaker-dialogue-w14-input-api-market.wav)

```json
{
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/speaker-dialogue-w14-input-api-market.wav"
}
```

### Example Output
The API returned the URL of a JSON file. Its content, with the embedding vectors shortened:

```json
{
  "segments": [
    {
      "speaker": "A",
      "start": "0:00:00.750938",
      "stop": "0:00:06.134063",
      "transcript": [
        { "start": "0:00:00.750938", "text": " Hey there, my name is Tara." },
        { "start": "0:00:03.430938", "text": " And I'm the speech generation model" },
        { "start": "0:00:04.910938", "text": " that can sound like a person." }
      ]
    },
    {
      "speaker": "B",
      "start": "0:00:07.365937",
      "stop": "0:00:17.912813",
      "transcript": [
        { "start": "0:00:07.365937", "text": " The little tales they tell are false." },
        { "start": "0:00:11.525937", "text": " The door was barred, locked, and bolted as well." },
        { "start": "0:00:15.805937", "text": " Ripe pears are fit for a queen's table." }
      ]
    }
  ],
  "speakers": {
    "count": 2,
    "labels": ["A", "B"],
    "embeddings": {
      "A": [-7.105358600616455, -10.964811325073242, 16.588359832763672],
      "B": [-14.551253318786621, -24.721473693847656, 18.251371383666992]
    }
  }
}
```

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `audio` | string (URL) | Yes |  |  | Audio file (URL) to transcribe. |
| `prompt` | string | No | none |  | Optional text passed as a prompt to each Whisper call, for example names or terms that appear in the audio. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0044 per API unit.
- **1 API unit = 1 request with up to 17 seconds of processing.** A request that takes longer is billed one more unit for each started 17-second block (for example, 40 seconds of processing is 3 units, $0.0132).
- Longer audio takes longer to process and adds units.
- **Example cost**: the example request took 8.1 seconds of processing, which is 1 unit ($0.0044).
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/whisper-speaker-diarization-meronym-speaker-transcription`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/whisper-speaker-diarization-meronym-speaker-transcription/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "9950ee297f0fdad8736adf74ada54f63cc5b5bdfd5b2187366910ed5baf1a7a1",
    "input": {
      "audio": "https://blog.api.market/wp-content/uploads/2026/10/speaker-dialogue-w14-input-api-market.wav"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "bqksyjdf4hrge0d1f1nasp8gam",
  "version": "9950ee297f0fdad8736adf74ada54f63cc5b5bdfd5b2187366910ed5baf1a7a1",
  "status": "starting",
  "created_at": "2026-10-26T13:33:40.158Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/whisper-speaker-diarization-meronym-speaker-transcription/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "bqksyjdf4hrge0d1f1nasp8gam",
  "status": "succeeded",
  "output": "https://cdn.api.market/ALMUc-PaX7msC8_l7hSRRITqOv7TEuwI/-/czjl/oJ1GaC1agNJFGVftKI0hrwysJVm9vCNMNMoMPeQQkKBRmQbXA/output.json",
  "error": null,
  "created_at": "2026-10-26T13:33:40.158Z",
  "started_at": "2026-10-26T13:37:13.809Z",
  "completed_at": "2026-10-26T13:37:21.954Z"
}
```

`output` is a single URL string pointing to a JSON file with `segments` (each with `speaker`, `start`, `stop` and a `transcript` list of `start` and `text` entries) and `speakers` (`count`, `labels` and one `embeddings` vector per label). Download the file to read the transcript.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `audio`.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/whisper-speaker-diarization-meronym-speaker-transcription";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "9950ee297f0fdad8736adf74ada54f63cc5b5bdfd5b2187366910ed5baf1a7a1", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/speaker-dialogue-w14-input-api-market.wav"
}).then(async (url) => console.log(JSON.stringify(await (await fetch(url)).json(), null, 2)));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/whisper-speaker-diarization-meronym-speaker-transcription"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "9950ee297f0fdad8736adf74ada54f63cc5b5bdfd5b2187366910ed5baf1a7a1", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


result_url = create_and_wait_for_prediction({
    "audio": "https://blog.api.market/wp-content/uploads/2026/10/speaker-dialogue-w14-input-api-market.wav",
})
print(requests.get(result_url).json())
```

## FAQ
- **What does the output contain?**
  - A URL to a JSON file. The file has `segments` (speaker label, start and stop time, and the timestamped text) and `speakers` (count, labels and one embedding vector per speaker).
- **How are speakers named?**
  - Speakers get letter labels (`A`, `B`, ...) in the order they are detected. Map them to real names yourself.
- **What is `prompt` for?**
  - It is passed to every Whisper call. Use it to give spellings of names, products or terms that appear in the recording.
- **How much does a request cost?**
  - $0.0044 for each started 17 seconds of processing. The example recording took 8.1 seconds and cost 1 unit ($0.0044); longer recordings take longer and use more units.
- **Do I need to set the number of speakers?**
  - No. There is no speaker-count input; the number of speakers is detected and returned in `speakers.count`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Transcribe audio and split it by speaker with Whisper: transcripts, speaker labels, timestamps and embeddings as JSON. $0.0044 per request.