PYpyannote
Api
Operations

Diarize audio

Changed on
post/v1/diarize

Request

  • Base URL
    https://api.pyannote.ai
  • URL
    https://api.pyannote.ai/v1/diarize
  • Auth
    HTTP bearer

Request body

urlstring required

URL of the audio file to be processed

webhookstring

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

webhookStatusOnlyboolean

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

model'precision-3' | 'precision-2' | 'community-1' nullable

Diarization model to use

numSpeakersnumber

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

minSpeakersnumber

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

maxSpeakersnumber

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

vadSensitivitynumber

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.

crosstalkSensitivitynumber

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.

turnLevelConfidenceboolean

Includes turn-level confidence values in the output.

speechProbabilityboolean

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

crosstalkProbabilityboolean

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

speakerProbabilityboolean

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

exclusiveboolean

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

confidenceboolean

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.

transcriptionboolean

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

Example request

{
  "url": "https://example.com/audio.wav",
  "webhook": "https://example.com/webhook",
  "webhookStatusOnly": true,
  "model": "precision-2",
  "numSpeakers": 2,
  "minSpeakers": 1,
  "maxSpeakers": 4,
  "turnLevelConfidence": true,
  "speechProbability": true,
  "crosstalkProbability": true,
  "speakerProbability": true,
  "exclusive": true,
  "confidence": true,
  "transcriptionConfig": {
    "model": "faster-whisper-large-v3-turbo"
  }
}

Response

jobIdstring required

ID of the job

status'pending' | 'created' | 'succeeded' | 'canceled' | 'failed' | 'running' required

Status of the job

warningstring

Warning message if any

Example response

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

Changes

  • 098a8442f5f6Revision changes
    • breaking

      the request property became not nullable

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new precision-3 enum value to the request property