How to identify speakers with voiceprints

Speaker identification is the process of determining who is speaking in an audio file by comparing their voice characteristics against known voiceprints. Unlike diarization which only separates speakers into generic labels (SPEAKER_00, SPEAKER_01, etc.), identification assigns specific identities to speakers.

What are voiceprints?

A voiceprint is a unique digital representation of a person’s voice characteristics, similar to a fingerprint but for voice. It captures the distinctive features of how someone speaks, allowing the system to recognize that person in future audio recordings.

You manage your voiceprints

Voiceprints are used only for identification. They do not improve diarization accuracy.
pyannoteAI does not maintain a reusable voiceprint database for your account.
Voiceprint job output, like all job output, is deleted 24 hours after job completion. Retrieve it and store it in your own secure data store.

Voiceprint requirements

One voiceprint per speaker: Create only one voiceprint for each person.
Single speaker only: The recording must contain only the target speaker’s voice with no overlapping speakers.
Maximum duration: Audio samples must be at most 30 seconds long for creating voiceprints.
Consistent speaking style: The voiceprint should capture the person’s normal speaking voice.
Language: Our models are language agnostic, so voiceprints can be created in any spoken language.

Prerequisites

Before you start, you’ll need:

pyannoteAI account with credit or active subscription
An API key
An audio recording of a single speaker for the voiceprint creation
An audio recording with multiple speakers for diarization + identification

For help creating an account and getting your API key, see the quickstart guide. For pricing and charging details, see Billing.

1. Create a voiceprint

First, create one voiceprint for each speaker you want to identify. After creation, retrieve the voiceprint and store it in your own secure data store. Send a POST request to the voiceprint endpoint with an audio file containing the speaker’s voice.

create_voiceprint.py

import requests

url = "https://api.pyannote.ai/v1/voiceprint"
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://example.com/speaker-voice-sample.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())

# 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/voiceprint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/speaker-voice-sample.wav"}'

const url = "https://api.pyannote.ai/v1/voiceprint";
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://example.com/speaker-voice-sample.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 to track the voiceprint creation:

Example response

{
  "jobId": "3c8a89a5-dcc6-4edb-a75d-ffd64739674d",
  "status": "created"
}

Get voiceprint results

To retrieve the voiceprint results, use the same polling or webhook approach described in the How to diarize an audio file tutorial. The process works identically for voiceprint jobs.

Save voiceprints to your own data storage

Job outputs, including voiceprints, are automatically deleted 24 hours after job completion.
Voiceprints are reusable, so retrieve and store them securely for future identification requests.
See Data retention for the full policy.

example job voiceprint output

{
  "jobId": "3c8a89a5-dcc6-4edb-a75d-ffd64739674d",
  "status": "succeeded",
  "createdAt": "2024-02-20T12:00:00Z",
  "updatedAt": "2024-02-20T12:00:00Z",
  "output": {
    "voiceprint": "U29tZVZvaWNlUHJpbnREYXRhMQ=="
  }
}

2. Identify speakers in audio

Retrieve the voiceprints from your own data store and include them in the voiceprints array. Each identification request is independent and only uses the voiceprints included in that request. Send a POST request to the identify endpoint with the audio file URL and the voiceprints you want to match against.

identify_speakers.py

import requests

url = "https://api.pyannote.ai/v1/identify"
api_key = "YOUR_API_KEY"

headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
data = {
    "url": "https://example.com/meeting-audio.wav",
    "voiceprints": [
        {
            "label": "John Doe", # The speaker label you want to assign
            "voiceprint": "U29tZVZvaWNlUHJpbnREYXRhMQ=="  # Replace with actual voiceprint
        },
        # Add more voiceprints as needed
    ],
    # Optional matching parameters
    "matching": {
        "threshold": 50,  # Only match if confidence is 50% or higher
        "exclusive": True  # Prevent multiple speakers matching same voiceprint
    }
}

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

curl -X POST "https://api.pyannote.ai/v1/identify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/meeting-audio.wav",
    "voiceprints": [
    {
      "label": "John Doe",
      "voiceprint": "U29tZVZvaWNlUHJpbnREYXRhMQ=="
    }
    ],
    "matching": {
      "threshold": 50,
      "exclusive": true
    }
  }'

const url = "https://api.pyannote.ai/v1/identify";
const apiKey = "YOUR_API_KEY";
const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};
const data = {
  url: "https://example.com/meeting-audio.wav",
  voiceprints: [
    {
      label: "John Doe", // The speaker label you want to assign
      voiceprint: "U29tZVZvaWNlUHJpbnREYXRhMQ==", // Replace with actual voiceprint
    },
    // Add more voiceprints as needed
  ],
  // Optional matching parameters
  matching: {
    threshold: 50, // Only match if confidence is 50% or higher
    exclusive: true, // Prevent multiple speakers matching same voiceprint
  },
};

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 for tracking the identification job:

Example response

{
  "jobId": "4d9b9ab6-edd7-5feca-b86e-gee75840775e",
  "status": "created"
}

Multiple voiceprints: You can add multiple voiceprints for different people in the same request. Each voiceprint must have a unique label. The system will attempt to match all provided voiceprints against the audio.

Voiceprint selection: Include voiceprints only for speakers you expect to be in the recording. If you are unsure whether a speaker is present, set an appropriate matching.threshold and review the confidence scores. A submitted voiceprint may match a speaker even when that person is not in the recording.

3. Get identification results

To retrieve the identification results, use the same polling or webhook approach described in the How to diarize an audio file tutorial. The process works identically for identification jobs.

Example identification output

{
  "jobId": "4d9b9ab6-edd7-5feca-b86e-gee75840775e",
  "status": "succeeded",
  "createdAt": "2025-11-06T09:07:49.932Z",
  "updatedAt": "2025-11-06T09:07:53.229Z",
  "output": {
    "diarization": [
      {
        "speaker": "SPEAKER_00",
        "start": 3.005,
        "end": 5.945
      },
      {
        "speaker": "SPEAKER_01",
        "start": 6.345,
        "end": 9.565
      },
      ...
    ],
    "identification": [
      {
        "speaker": "John Doe",
        "start": 3.005,
        "end": 5.945,
        "diarizationSpeaker": "SPEAKER_00",
        "match": "John Doe"
      },
      {
        "speaker": "SPEAKER_01",
        "start": 6.345,
        "end": 9.565,
        "diarizationSpeaker": "SPEAKER_01",
        "match": null
      },
      ...
    ],
    "voiceprints": [
      {
        "speaker": "SPEAKER_00",
        "match": "John Doe",
        "confidence": {
          "John Doe": 86
        }
      },
      {
        "speaker": "SPEAKER_01",
        "match": null,
        "confidence": {
          "John Doe": 16
        }
      }
    ]
  }
}

Learn more details about each parameter of the identification output in the identification schema reference.

Understanding the Results

Diarization vs Identification

Diarization: Separates audio into speaker segments with generic labels (SPEAKER_00, SPEAKER_01, etc.)
Identification: Matches those segments to known voiceprints with specific labels (John Doe, Jane Smith, etc.)

Confidence scores

The confidence scores show how well each voiceprint matches each speaker segment:

Higher scores indicate better matches
Use the threshold parameter to filter out low-confidence matches
Consider the context when interpreting confidence scores

Matching options

matching.threshold: Minimum confidence score required for a match (0-100, default: 0). Set higher values (50-70) for more strict matching, lower values for more lenient matching.
matching.exclusive: Prevent multiple speakers from matching the same voiceprint (default: true). Set to false if you want multiple speakers to potentially match the same voiceprint.

Pricing

/identify jobs are billed based on the audio duration sent for processing, with a 20-second minimum per successful job, and /voiceprint jobs are billed per voiceprint created. See Billing for details.

Getting Started

Tutorials

Webhooks

Support

Administration

How to identify speakers with voiceprints

What are voiceprints?

Voiceprint requirements

Prerequisites

1. Create a voiceprint

Get voiceprint results

2. Identify speakers in audio

3. Get identification results

Understanding the Results

Diarization vs Identification

Confidence scores

Matching options

Pricing

​What are voiceprints?

​Voiceprint requirements

​Prerequisites

​1. Create a voiceprint

​Get voiceprint results

​2. Identify speakers in audio

​3. Get identification results

​Understanding the Results

​Diarization vs Identification

​Confidence scores

​Matching options

​Pricing

What are voiceprints?

Voiceprint requirements

Prerequisites

1. Create a voiceprint

Get voiceprint results

2. Identify speakers in audio

3. Get identification results

Understanding the Results

Diarization vs Identification

Confidence scores

Matching options

Pricing