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

# How to diarize an audio file

> This tutorial shows how to diarize an audio file using the pyannoteAI API

### Prerequisites

Before you start, you'll need:

* pyannoteAI account with credit or active subscription
* An API key from your dashboard
* A publicly accessible audio file URL

For help creating an account and getting your API key, see the [quickstart guide](https://docs.pyannote.ai/quickstart.md). For pricing and charging details, see [Billing](https://docs.pyannote.ai/administration/billing.md).

## 1. Diarize API request

Send a POST request to the diarize endpoint with your audio file URL.

In our example we use a sample audio file hosted on pyannoteAI servers. Its a 79 second recording with two speakers. You may use this url to test the API: `https://files.pyannote.ai/marklex1min.wav`

> [!NOTE]
>
> **The URL must be a direct link to a publicly accessible audio file.** Make sure the URL points directly to the file (e.g., ends with `.wav`, `.mp3`, etc.) and is accessible without authentication.
>
> Typically, you'll use a signed URL from cloud storage such as AWS S3 buckets or other cloud storage services. **We also offer our own upload file solution.** For details on uploading audio files to our servers, see:
>
> * [How to upload an audio file](https://docs.pyannote.ai/tutorials/how-to-upload-files.md)

```python diarize.py theme={null}
import requests

url = "https://api.pyannote.ai/v1/diarize"
api_key = "YOUR_API_KEY"  # In production, use environment variables: os.getenv("PYANNOTE_API_KEY")

headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
data = {"url": "https://files.pyannote.ai/marklex1min.wav"}

response = requests.post(url, headers=headers, json=data)

if response.status_code != 200:
    print(f"Error: {response.status_code} - {response.text}")
else:
    print(response.json())
```

```bash theme={null}
# Set your API key as an environment variable in production
# export PYANNOTE_API_KEY="your_api_key_here"
curl -X POST "https://api.pyannote.ai/v1/diarize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://files.pyannote.ai/marklex1min.wav"}'
```

```typescript diarize.ts theme={null}
const url = "https://api.pyannote.ai/v1/diarize";
const apiKey = "YOUR_API_KEY"; // In production, use environment variables: process.env.PYANNOTE_API_KEY
const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};
const data = {
  url: "https://files.pyannote.ai/marklex1min.wav",
};

const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(data),
});

if (!response.ok) {
  console.error(`Error: ${response.status} - ${await response.text()}`);
} else {
  console.log(await response.json());
}
```

The response will include a `jobId` that you can use to track the diarization job progress:

```json Example response theme={null}
{
  "jobId": "3c8a89a5-dcc6-4edb-a75d-ffd64739674d",
  "status": "created"
}
```

***

## 2. Get diarization result

Once you have a `jobId`, you can retrieve the results using either polling or using webhooks:

> [!WARNING]
>
> **Job results are automatically deleted after 24 hours**, for all endpoints. Make sure to save your results in your own database.

### &#x20;Polling

Poll the [get job](https://docs.pyannote.ai/api-reference/get-job.md) endpoint to check job status and retrieve results when complete.

> [!NOTE]
>
> Be cautious of [rate limits](https://docs.pyannote.ai/ratelimits.md) when polling. Excessive requests can lead to rate limiting. **In production, we strongly recommend using webhooks instead.**

```python polling.py theme={null}
import time

api_key = "YOUR_API_KEY"  # In production, use environment variables: os.getenv("PYANNOTE_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

while True:
    response = requests.get(
        f"https://api.pyannote.ai/v1/jobs/{job_id}", headers=headers
    )

    if response.status_code != 200:
        print(f"Error: {response.status_code} - {response.text}")
        break

    data = response.json()
    status = data["status"]

    if status in ["succeeded", "failed", "canceled"]:
        if status == "succeeded":
            print("Job completed successfully!")
            print(data["output"])
        else:
            print(f"Job {status}")
        break

    print(f"Job status: {status}, waiting...")
    time.sleep(10)  # Wait 10 seconds before polling again
```

```bash theme={null}
# Set your API key as an environment variable in production
# export PYANNOTE_API_KEY="your_api_key_here"
# Poll for job status
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.pyannote.ai/v1/jobs/YOUR_JOB_ID"

# Keep polling until status is "succeeded", "failed", or "canceled"
```

```typescript polling.ts theme={null}
const jobId = "YOUR_JOB_ID"; // From the diarize response
const apiKey = "YOUR_API_KEY"; // In production, use environment variables: process.env.PYANNOTE_API_KEY
const headers = {
  Authorization: `Bearer ${apiKey}`,
};

async function pollJob() {
  while (true) {
    const response = await fetch(`https://api.pyannote.ai/v1/jobs/${jobId}`, {
      headers,
    });

    if (!response.ok) {
      console.error(`Error: ${response.status} - ${await response.text()}`);
      break;
    }

    const data = await response.json();
    const status = data.status;

    if (["succeeded", "failed", "canceled"].includes(status)) {
      if (status === "succeeded") {
        console.log("Job completed successfully!");
        console.log(data.output);
      } else {
        console.log(`Job ${status}`);
      }
      break;
    }

    console.log(`Job status: ${status}, waiting...`);
    await new Promise((resolve) => setTimeout(resolve, 10000)); // Wait 10 seconds
  }
}

pollJob();
```

### &#x20;Webhook

Specify a webhook URL when creating the diarization job to receive updates automatically when the job reaches a terminal status.

> [!NOTE]
>
> Webhooks are sent for terminal statuses only: `succeeded`, `failed`, and `canceled`. They are not sent for `pending`, `created`, or `running`.
>
> For `failed` and `canceled` jobs, payloads include `jobId` and `status` (without `output`).

#### 1. Specify your webhook URL

Add the `webhook` parameter to your diarization request payload. If you only need status updates (useful for smaller payloads), set `webhookStatusOnly` to `true` (default is `false`):

```python diarize_with_webhook.py theme={null}
data = {
    "url": "https://files.pyannote.ai/marklex1min.wav",
    "webhook": "https://your-server.com/webhook"
}
```

```bash theme={null}
-d '{
"url": "https://files.pyannote.ai/marklex1min.wav",
"webhook": "https://your-server.com/webhook"
}'
```

```typescript diarize_with_webhook.ts theme={null}
const data = {
  url: "https://files.pyannote.ai/marklex1min.wav",
  webhook: "https://your-server.com/webhook"
};
```

#### 2. Create server exposing webhook endpoint

Here we show a simple example of how to expose a server that accepts the webhook POST requests. You can use any web framework of your choice.

```python webhook.py theme={null}
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    status = data.get('status')

    if status == 'succeeded':
        print("Diarization completed!")
        print("Job ID:", data['jobId'])
        if 'output' in data:
            print("Results:", data['output'])

    if status == 'failed':
        print("Job failed.")

    if status == 'canceled':
        print("Job canceled.")

    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(port=5000)
```

```typescript webhook.ts theme={null}
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
    const data = req.body;
    const status = data.status;

    if (status === 'succeeded') {
        console.log('Diarization completed!');
        console.log('Job ID:', data.jobId);
        if (data.output) {
            console.log('Results:', data.output);
        }
    }

    if (status === 'failed') {
        console.log('Job failed.');
    }

    if (status === 'canceled') {
        console.log('Job canceled.');
    }

    res.json({ status: 'received' });
});

app.listen(5000, () => {
    console.log('Server running on port 5000');
});
```

> [!TIP]
>
> You can also use a tool like [ngrok](https://ngrok.com/) to expose your local server to the internet for testing webhooks, or use [webhook.site](https://webhook.site/) for quick testing.

**Learn more about webhooks:**

* [Receiving webhooks](https://docs.pyannote.ai/webhooks/receiving-webhooks.md) - Learn about webhook payloads, retries, and failure codes
* [Verifying webhooks](https://docs.pyannote.ai/webhooks/verifying-webhooks.md) - Learn how to verify webhook signatures to ensure requests are from pyannoteAI

## Pricing

Diarization jobs are billed based on the audio duration sent for processing, with a 20-second minimum per successful job. See [Billing](https://docs.pyannote.ai/administration/billing.md) for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.