Submit Diarization Job

Diarize audio

curl --request POST \
  --url https://api.pyannote.ai/v1/diarize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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,
  "transcription": false,
  "transcriptionConfig": {
    "model": "faster-whisper-large-v3-turbo"
  }
}
'

import requests

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

payload = {
    "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,
    "transcription": False,
    "transcriptionConfig": { "model": "faster-whisper-large-v3-turbo" }
}
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({
    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,
    transcription: false,
    transcriptionConfig: {model: 'faster-whisper-large-v3-turbo'}
  })
};

fetch('https://api.pyannote.ai/v1/diarize', 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/diarize",
  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([
    '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,
    'transcription' => false,
    'transcriptionConfig' => [
        'model' => 'faster-whisper-large-v3-turbo'
    ]
  ]),
  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/diarize"

	payload := strings.NewReader("{\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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\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/diarize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\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

diarize

Diarize audio

curl --request POST \
  --url https://api.pyannote.ai/v1/diarize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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,
  "transcription": false,
  "transcriptionConfig": {
    "model": "faster-whisper-large-v3-turbo"
  }
}
'

import requests

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

payload = {
    "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,
    "transcription": False,
    "transcriptionConfig": { "model": "faster-whisper-large-v3-turbo" }
}
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({
    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,
    transcription: false,
    transcriptionConfig: {model: 'faster-whisper-large-v3-turbo'}
  })
};

fetch('https://api.pyannote.ai/v1/diarize', 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/diarize",
  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([
    '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,
    'transcription' => false,
    'transcriptionConfig' => [
        'model' => 'faster-whisper-large-v3-turbo'
    ]
  ]),
  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/diarize"

	payload := strings.NewReader("{\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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\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/diarize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"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  \"transcription\": false,\n  \"transcriptionConfig\": {\n    \"model\": \"faster-whisper-large-v3-turbo\"\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 from a remote audio URL.

Diarization and transcription output is deleted 24 hours after job completion

Retrieve and store any output that you need before it is deleted.
See Data retention for the full policy.

For comprehensive guides on diarization, see these tutorials:

How to Diarize Audio - Complete diarization workflow
Diarization and Speech-to-Text Merge - Combining diarization with transcription
How to Upload Files - Working with local files
Speaker Configuration - Configuring speaker counts and overlapping speech
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

url

string

required

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,

community-1,

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

transcription

boolean

default:false

Enable speaker attributed transcription. Supported by the precision-2 and precision-3 diarization models.

transcriptionConfig

object

Transcription configuration, if transcription: true

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

Authorizations

Body

Response