Speaker Diarization
Identify and segment speakers throughout a conversation
1. Submit job
Endpoint
POSThttps://speakerscope.ai/api/diarization
Fields
| Field | Type | Description |
|---|---|---|
audio_url | string | URL of the audio file |
num_speakers | int (optional) | Exact number of speakers |
min_speakers | int (optional) | Minimum number of speakers |
max_speakers | int (optional) | Maximum number of speakers |
transcription_api_key | string (optional) | OpenAI API key to enable transcription |
Example
import requests
response = requests.post(
"https://speakerscope.ai/api/diarization",
auth=("<API_KEY>", "<API_SECRET>"),
json={
"audio_url": "<AUDIO_URL>",
# "num_speakers": <int>, # optional
# "min_speakers": <int>, # optional
# "max_speakers": <int>, # optional
# "transcription_api_key": <string>, # optional
},
)
print(response.json())Response
| Field | Type | Description |
|---|---|---|
job_id | str | Job identifier used to poll for the result |
{
"job_id": "cca90f61-c3f4-496b-a33c-6d77a4ce92bf"
}2. Get results
Endpoint
GEThttps://speakerscope.ai/api/status/{job_id}
Example
import requests
response = requests.get(
"https://speakerscope.ai/api/status/<JOB_ID>",
auth=("<API_KEY>", "<API_SECRET>"),
)
print(response.json())Response
Status
| Field | Type | Description |
|---|---|---|
status | str | "pending", "completed", or "failed" |
progress | str (optional) | Progress description (when "pending") |
error | str (optional) | Error message (when "failed") |
Transcription
| Field | Type | Description |
|---|---|---|
transcription | list[dict] (optional) | Transcript segments in chronological order (when status is "completed" and transcription_api_key was provided) |
transcription[].speaker | str | Speaker label (e.g. "SPEAKER_01", "SPEAKER_02") |
transcription[].start | float | Segment start time in seconds |
transcription[].end | float | Segment end time in seconds |
transcription[].text | str | Transcribed text for this segment |
Speaker Segments
| Field | Type | Description |
|---|---|---|
speaker_segments | list[dict] | List of speaker segments in chronological order (when status is "completed") |
speaker_segments[].speaker | str | Speaker label (e.g. "SPEAKER_01", "SPEAKER_02") |
speaker_segments[].start | float | Segment start time in seconds |
speaker_segments[].end | float | Segment end time in seconds |
Pending
{
"status": "pending",
"progress": "Predicting..."
}Completed
{
"status": "completed",
"transcription": [
{ "speaker": "SPEAKER_01", "start": 0.0, "end": 5.2, "text": "Hey, how are you doing?" },
{ "speaker": "SPEAKER_02", "start": 5.4, "end": 12.8, "text": "I'm doing well, thanks! How about you?" },
...
],
"speaker_segments": [
{ "speaker": "SPEAKER_01", "start": 0.0, "end": 5.2 },
{ "speaker": "SPEAKER_02", "start": 5.4, "end": 12.8 },
{ "speaker": "SPEAKER_01", "start": 13.1, "end": 19.7 },
{ "speaker": "SPEAKER_02", "start": 20.0, "end": 28.3 },
...
]
}