Speaker Diarization

Pre-recorded Streaming:NovaStreaming: Flux All available languages

Deepgram offers versioned diarization models. Use the diarize_model parameter to select a specific version:

• New integrations: Use diarize_model=latest to always get the newest available diarizer.
• Pin a specific version: Use diarize_model=v1 or diarize_model=v2 (batch only).
• Streaming: Use diarize_model=latest or diarize_model=v1. The v2 diarizer is not available for streaming and returns a validation error.

Use the diarize_model parameter to enable diarization and select the model version in a single parameter:

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?diarize_model=latest'

The boolean diarize parameter continues to work and always routes to the v1 diarizer:

diarize=true

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?diarize=true'

Switch your diarize=true requests to diarize_model (use latest for most cases). Don’t set both diarize and diarize_model — requests that set both are rejected.

Diarization is compatible with all Nova batch models (Nova-1, Nova-2, Nova-3) as well as enhanced and base. Whisper is not supported.

diarize_model is accepted on streaming requests with the following values:

• diarize_model=v1 — uses the v1 streaming diarizer.
• diarize_model=latest — resolves to the latest streaming diarizer (currently v1).
• diarize_model=v2 — not supported on streaming. Returns a validation error.

The deprecated diarize=true parameter also continues to work for streaming and routes to the v1 diarizer.

When the file is finished processing, you’ll receive a JSON response. Let’s look more closely at the words object within the alternatives object within this response.

When using diarization for pre-recorded audio, both speaker and speaker_confidence values will be returned:

...
"alternatives":[
  {
    ...
    "words": [
      {
        "word":"hello",
        "start":15.259043,
        "end":15.338787,
        "confidence":0.9721591,
        "speaker":0,
        "speaker_confidence":0.5853265
      },
    ...
    ]
  }
]

When using diarization for live streaming audio, only the speaker value will be returned:

...
"alternatives":[
  {
    ...
    "words": [
      {
        "word":"hello",
        "start":15.259043,
        "end":15.338787,
        "confidence":0.9721591,
        "speaker":0
      },
    ...
    ]
  }
]

When a diarizer runs, the response metadata includes a diarize_info object that identifies the diarizer build that produced the speaker labels. It appears alongside model_info in both pre-recorded and streaming responses, which makes the resolved model visible when diarize_model=latest resolves to different versions across batch and streaming:

"metadata": {
  "models": ["30089e05-99d1-4376-b32e-c263170674af"],
  "model_info": {
    "30089e05-99d1-4376-b32e-c263170674af": {
      "name": "2-general-nova",
      "version": "2024-01-09.29447",
      "arch": "nova-2"
    }
  },
  "diarize_info": {
    "model_uuid": "9a1c8b3e-2f44-4c8a-b1d0-example0000",
    "arch": "v2"
  }
}

• model_uuid — the UUID of the diarizer build that ran.
• arch — the diarizer architecture family (v1 or v2) that diarize_model resolved to, which makes diarize_model=latest resolution visible. Legacy diarize=true requests report v1.

diarize_info is present only when a diarizer actually ran:

To improve readability, you can use a JSON processor to parse the JSON. In this example, we use JQ and further improve readability by turning on Deepgram’s punctuation and utterances features:

curl \
  --request POST \
  --url 'https://api.deepgram.com/v1/listen?diarize_model=latest&punctuate=true&utterances=true' \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'content-type: audio/mp3' \
  --data-binary @Premier_broken-phone_numbers.mp3 | jq -r ".results.utterances[] | \"[Speaker:\(.speaker)] \(.transcript)\""

When the file is finished processing, you’ll receive the following response:

[Speaker:0] Hello, and thank you for calling premier phone service. Please be aware that this call may be recorded for quality and training purposes.
[Speaker:0] My name is Beth, and I will be assisting you today. How are you doing?
[Speaker:1] Not too bad. How are you today?
[Speaker:0] I'm doing well. Thank you. May I please have your name?
[Speaker:1] My name is Blake...

What’s Next

• Understanding When to Use the Multichannel and Diarization Features