Submit Identification Job

Identify speaker with diarization

curl --request POST \
  --url https://api.pyannote.ai/v1/identify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voiceprints": [
    {
      "label": "John Doe",
      "voiceprint": "U29tZUJhc2U2NERhdGE"
    }
  ],
  "url": "https://example.com/audio.wav",
  "webhook": "https://example.com/webhook",
  "webhookStatusOnly": true,
  "model": "precision-2",
  "numSpeakers": 2,
  "minSpeakers": 1,
  "maxSpeakers": 4,
  "vadSensitivity": 0,
  "crosstalkSensitivity": 0,
  "turnLevelConfidence": true,
  "exclusive": true,
  "confidence": true,
  "speechProbability": true,
  "crosstalkProbability": true,
  "speakerProbability": true,
  "matching": {
    "exclusive": true,
    "threshold": 0
  }
}
'

import requests

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

payload = {
    "voiceprints": [
        {
            "label": "John Doe",
            "voiceprint": "U29tZUJhc2U2NERhdGE"
        }
    ],
    "url": "https://example.com/audio.wav",
    "webhook": "https://example.com/webhook",
    "webhookStatusOnly": True,
    "model": "precision-2",
    "numSpeakers": 2,
    "minSpeakers": 1,
    "maxSpeakers": 4,
    "vadSensitivity": 0,
    "crosstalkSensitivity": 0,
    "turnLevelConfidence": True,
    "exclusive": True,
    "confidence": True,
    "speechProbability": True,
    "crosstalkProbability": True,
    "speakerProbability": True,
    "matching": {
        "exclusive": True,
        "threshold": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voiceprints: [{label: 'John Doe', voiceprint: 'U29tZUJhc2U2NERhdGE'}],
    url: 'https://example.com/audio.wav',
    webhook: 'https://example.com/webhook',
    webhookStatusOnly: true,
    model: 'precision-2',
    numSpeakers: 2,
    minSpeakers: 1,
    maxSpeakers: 4,
    vadSensitivity: 0,
    crosstalkSensitivity: 0,
    turnLevelConfidence: true,
    exclusive: true,
    confidence: true,
    speechProbability: true,
    crosstalkProbability: true,
    speakerProbability: true,
    matching: {exclusive: true, threshold: 0}
  })
};

fetch('https://api.pyannote.ai/v1/identify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pyannote.ai/v1/identify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'voiceprints' => [
        [
                'label' => 'John Doe',
                'voiceprint' => 'U29tZUJhc2U2NERhdGE'
        ]
    ],
    'url' => 'https://example.com/audio.wav',
    'webhook' => 'https://example.com/webhook',
    'webhookStatusOnly' => true,
    'model' => 'precision-2',
    'numSpeakers' => 2,
    'minSpeakers' => 1,
    'maxSpeakers' => 4,
    'vadSensitivity' => 0,
    'crosstalkSensitivity' => 0,
    'turnLevelConfidence' => true,
    'exclusive' => true,
    'confidence' => true,
    'speechProbability' => true,
    'crosstalkProbability' => true,
    'speakerProbability' => true,
    'matching' => [
        'exclusive' => true,
        'threshold' => 0
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pyannote.ai/v1/identify")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyannote.ai/v1/identify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "message": "Invalid request",
  "errors": [
    {
      "field": "url",
      "message": "Invalid URL"
    }
  ]
}

{
  "requestId": "37a4c3a0-b034-4e8c-9ed9-76da6645544a",
  "message": "Error message"
}

{
  "requestId": "37a4c3a0-b034-4e8c-9ed9-76da6645544a",
  "message": "Error message"
}

POST

identify

Identify speaker with diarization

curl --request POST \
  --url https://api.pyannote.ai/v1/identify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voiceprints": [
    {
      "label": "John Doe",
      "voiceprint": "U29tZUJhc2U2NERhdGE"
    }
  ],
  "url": "https://example.com/audio.wav",
  "webhook": "https://example.com/webhook",
  "webhookStatusOnly": true,
  "model": "precision-2",
  "numSpeakers": 2,
  "minSpeakers": 1,
  "maxSpeakers": 4,
  "vadSensitivity": 0,
  "crosstalkSensitivity": 0,
  "turnLevelConfidence": true,
  "exclusive": true,
  "confidence": true,
  "speechProbability": true,
  "crosstalkProbability": true,
  "speakerProbability": true,
  "matching": {
    "exclusive": true,
    "threshold": 0
  }
}
'

import requests

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

payload = {
    "voiceprints": [
        {
            "label": "John Doe",
            "voiceprint": "U29tZUJhc2U2NERhdGE"
        }
    ],
    "url": "https://example.com/audio.wav",
    "webhook": "https://example.com/webhook",
    "webhookStatusOnly": True,
    "model": "precision-2",
    "numSpeakers": 2,
    "minSpeakers": 1,
    "maxSpeakers": 4,
    "vadSensitivity": 0,
    "crosstalkSensitivity": 0,
    "turnLevelConfidence": True,
    "exclusive": True,
    "confidence": True,
    "speechProbability": True,
    "crosstalkProbability": True,
    "speakerProbability": True,
    "matching": {
        "exclusive": True,
        "threshold": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voiceprints: [{label: 'John Doe', voiceprint: 'U29tZUJhc2U2NERhdGE'}],
    url: 'https://example.com/audio.wav',
    webhook: 'https://example.com/webhook',
    webhookStatusOnly: true,
    model: 'precision-2',
    numSpeakers: 2,
    minSpeakers: 1,
    maxSpeakers: 4,
    vadSensitivity: 0,
    crosstalkSensitivity: 0,
    turnLevelConfidence: true,
    exclusive: true,
    confidence: true,
    speechProbability: true,
    crosstalkProbability: true,
    speakerProbability: true,
    matching: {exclusive: true, threshold: 0}
  })
};

fetch('https://api.pyannote.ai/v1/identify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pyannote.ai/v1/identify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'voiceprints' => [
        [
                'label' => 'John Doe',
                'voiceprint' => 'U29tZUJhc2U2NERhdGE'
        ]
    ],
    'url' => 'https://example.com/audio.wav',
    'webhook' => 'https://example.com/webhook',
    'webhookStatusOnly' => true,
    'model' => 'precision-2',
    'numSpeakers' => 2,
    'minSpeakers' => 1,
    'maxSpeakers' => 4,
    'vadSensitivity' => 0,
    'crosstalkSensitivity' => 0,
    'turnLevelConfidence' => true,
    'exclusive' => true,
    'confidence' => true,
    'speechProbability' => true,
    'crosstalkProbability' => true,
    'speakerProbability' => true,
    'matching' => [
        'exclusive' => true,
        'threshold' => 0
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pyannote.ai/v1/identify")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyannote.ai/v1/identify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voiceprints\": [\n    {\n      \"label\": \"John Doe\",\n      \"voiceprint\": \"U29tZUJhc2U2NERhdGE\"\n    }\n  ],\n  \"url\": \"https://example.com/audio.wav\",\n  \"webhook\": \"https://example.com/webhook\",\n  \"webhookStatusOnly\": true,\n  \"model\": \"precision-2\",\n  \"numSpeakers\": 2,\n  \"minSpeakers\": 1,\n  \"maxSpeakers\": 4,\n  \"vadSensitivity\": 0,\n  \"crosstalkSensitivity\": 0,\n  \"turnLevelConfidence\": true,\n  \"exclusive\": true,\n  \"confidence\": true,\n  \"speechProbability\": true,\n  \"crosstalkProbability\": true,\n  \"speakerProbability\": true,\n  \"matching\": {\n    \"exclusive\": true,\n    \"threshold\": 0\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "message": "Invalid request",
  "errors": [
    {
      "field": "url",
      "message": "Invalid URL"
    }
  ]
}

{
  "requestId": "37a4c3a0-b034-4e8c-9ed9-76da6645544a",
  "message": "Error message"
}

{
  "requestId": "37a4c3a0-b034-4e8c-9ed9-76da6645544a",
  "message": "Error message"
}

This endpoint allows you to create a new diarization with speaker identification from a remote audio URL.

Identification output is deleted 24 hours after job completion

Include all voiceprints to match in each request. Voiceprints from previous jobs are not added automatically.
Retrieve and store any output that you need before it is deleted.
See Data retention for the full policy.

For a complete guide on speaker identification using voiceprints, see the Identification with Voiceprints tutorial. Identification jobs accept the same detection and scoring options as diarization:

VAD and Cross-talk Sensitivity - Tuning detection sensitivity (precision-3)
Output Scores - Confidence scores, and frame-level speech, cross-talk and speaker probabilities

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

voiceprints

object[]

required

List of voiceprints to identify against

Required array length: 1 - 50 elements

Show child attributes

url

string

URL of the audio file to be processed

Example:

"https://example.com/audio.wav"

webhook

string

Webhook URL to receive results when job is completed (optional)

Example:

"https://example.com/webhook"

webhookStatusOnly

boolean

default:false

When true, webhook payload only includes jobId and status (excludes output). Useful for large payloads.

Example:

true

model

enum<string> | null

default:precision-2

Available options:

precision-2,

precision-3

Example:

"precision-2"

numSpeakers

number

Number of speakers. Only use if the number of speakers is known in advance. Number of speakers is detected automatically if not provided. Setting this value results in better overall diarization performance. In rare cases where we cannot honor this request (e.g. short files and large number of speakers), a warning will be added to the output. Equivalent to sending minSpeakers==maxSpeakers

Required range: x >= 1

Example:

2

minSpeakers

number

Minimum number of speakers (must be <= maxSpeakers if both are set)

Required range: x >= 1

Example:

1

maxSpeakers

number

Maximum number of speakers (must be >= minSpeakers if both are set)

Required range: x >= 1

Example:

4

vadSensitivity

number

default:0

Controls the sensitivity of voice activity detection (VAD). Float in [-5.0, 5.0], defaults to 0.0 (balanced precision/recall). Higher values increase recall (less speech missed). Lower values increase precision (less non-speech detected as speech). Only available for the precision-3 model.

Required range: -5 <= x <= 5

Example:

0

crosstalkSensitivity

number

default:0

Controls the sensitivity of overlapping speech (cross-talk) detection. Float in [-5.0, 5.0], defaults to 0.0 (balanced precision/recall). Higher values increase recall (detect more overlapping speech). Lower values increase precision (detect only clear overlaps). Only available for the precision-3 model.

Required range: -5 <= x <= 5

Example:

0

turnLevelConfidence

boolean | null

default:false

Includes turn-level confidence values in the output.

Example:

true

exclusive

boolean

default:false

Includes exclusive diarization values in the output in exclusiveDiarization key (equivalent to diarization but without overlapping speech).

Example:

true

confidence

boolean

default:false

Include confidence values in the output. Output is considerably larger when this option is enabled. Output includes a list of confidence scores with a resolution. Not supported by the precision-3 model, which returns an error if this is set; use speechProbability, crosstalkProbability or speakerProbability instead.

Example:

true

speechProbability

boolean

default:false

Includes a frame-level speech probability curve in the output, in the speechProbability key. Only available for the precision-3 model.

Example:

true

crosstalkProbability

boolean

default:false

Includes a frame-level overlapping speech (cross-talk) probability curve in the output, in the crosstalkProbability key. Only available for the precision-3 model.

Example:

true

speakerProbability

boolean

default:false

Includes per-speaker, frame-level probability scores in the output, in the speakerProbability key. Only available for the precision-3 model.

Example:

true

matching

object

Customize how voiceprints are matched against speakers

Show child attributes

Response

jobId

string

required

ID of the job

Example:

"3c8a89a5-dcc6-4edb-a75d-ffd64739674d"

status

enum<string>

required

Status of the job

Available options:

pending,

created,

succeeded,

canceled,

failed,

running

Example:

"created"

warning

string

Warning message if any

Introduction

Test

Jobs

Streaming

Media

Schemas

Submit Identification Job

Authorizations

Body

Response