Speaker Intelligence
Analyze conversations with enhanced speaker insights
1. Submit job
Endpoint
POSThttps://speakerscope.ai/api/intelligence
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 |
speakers | dict[str, str] (optional) | Maps speaker names to a URL of a reference audio sample |
transcription_api_key | string (optional) | OpenAI API key to enable transcription |
Example
import requests
response = requests.post(
"https://speakerscope.ai/api/intelligence",
auth=("<API_KEY>", "<API_SECRET>"),
json={
"audio_url": "<AUDIO_URL>",
# "num_speakers": <int>, # optional
# "min_speakers": <int>, # optional
# "max_speakers": <int>, # optional
# "speakers": <dict[str, str]>, # 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 |
Emotion Segments
| Field | Type | Description |
|---|---|---|
emotion_segments | list[dict] | List of emotion segments in chronological order (when status is "completed") |
emotion_segments[].speaker | str | Speaker label (e.g. "SPEAKER_01", "SPEAKER_02") |
emotion_segments[].start | float | Segment start time in seconds |
emotion_segments[].end | float | Segment end time in seconds |
emotion_segments[].emotion | str | Predicted emotion ("neutral", "joy", "sad", "fear", "anger") |
emotion_segments[].probabilities | dict[str, float] | Maps emotion labels to their confidence scores, sorted in descending order |
Speakers
| Field | Type | Description |
|---|---|---|
speakers | dict[str, dict] | Maps each speaker label to their identity, gender, language, and emotion predictions (when status is "completed") |
speakers.<speaker>.identity.prediction | str (optional) | Name of the enrolled speaker that best matches this speaker or "Unknown" if no match (when speakers is provided) |
speakers.<speaker>.identity.probabilities | dict[str, float] (optional) | Maps each enrolled speaker name to their confidence scores, sorted in descending order |
speakers.<speaker>.gender.prediction | str | Predicted gender ("male" or "female") |
speakers.<speaker>.gender.probabilities | dict[str, float] | Maps gender labels to their confidence scores, sorted in descending order |
speakers.<speaker>.language.prediction | str | Predicted ISO 639-1 language code |
speakers.<speaker>.language.probabilities | dict[str, float] | Maps language codes to their confidence scores, sorted in descending order |
speakers.<speaker>.emotion_ratio | dict[str, float] | Proportion of this speaker's speech time attributed to each predicted emotion |
Statistics
| Field | Type | Description |
|---|---|---|
stats | dict | Aggregated statistics computed across the whole conversation (when status is "completed") |
stats.speech_ratio | float | Proportion of the audio containing speech |
stats.non_speech_ratio | float | Proportion of the audio containing no speech |
stats.speaker_ratio | dict[str, float] | Proportion of speech time attributed to each speaker |
stats.gender_ratio | dict[str, float] | Proportion of speech time attributed to each predicted gender |
stats.language_ratio | dict[str, float] | Proportion of speech time attributed to each predicted language |
stats.emotion_ratio | dict[str, float] | Proportion of speech time attributed to each predicted emotion |
Examples
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 },
...
],
"emotion_segments": [
{ "speaker": "SPEAKER_01", "start": 0.0, "end": 5.0, "emotion": "neutral", "probabilities": { "neutral": 0.64, "joy": 0.21, "sad": 0.08, "anger": 0.05, "fear": 0.02 } },
{ "speaker": "SPEAKER_02", "start": 5.4, "end": 10.4, "emotion": "joy", "probabilities": { "joy": 0.82, "neutral": 0.10, "sad": 0.04, "anger": 0.03, "fear": 0.01 } },
{ "speaker": "SPEAKER_01", "start": 13.1, "end": 18.1, "emotion": "anger", "probabilities": { "anger": 0.55, "neutral": 0.30, "sad": 0.09, "fear": 0.04, "joy": 0.02 } },
...
],
"speakers": {
"SPEAKER_01": {
"identity": {
"prediction": "Bob",
"probabilities": { "Bob": 0.93, "Alice": 0.07 }
},
"gender": {
"prediction": "male",
"probabilities": { "male": 0.97, "female": 0.03 }
},
"language": {
"prediction": "en",
"probabilities": { "en": 0.91, "fr": 0.05, "de": 0.02, ... }
},
"emotion_ratio": { "neutral": 0.58, "anger": 0.24, "joy": 0.12, "sad": 0.04, "fear": 0.02 }
},
"SPEAKER_02": {
"identity": {
"prediction": "Alice",
"probabilities": { "Alice": 0.89, "Bob": 0.11 }
},
"gender": {
"prediction": "female",
"probabilities": { "female": 0.98, "male": 0.02 }
},
"language": {
"prediction": "fr",
"probabilities": { "fr": 0.20, "en": 0.16, "de": 0.07, ... }
},
"emotion_ratio": { "joy": 0.71, "neutral": 0.19, "sad": 0.06, "anger": 0.03, "fear": 0.01 }
}
},
"stats": {
"speech_ratio": 0.71,
"non_speech_ratio": 0.29,
"speaker_ratio": { "SPEAKER_01": 0.77, "SPEAKER_02": 0.23 },
"gender_ratio": { "male": 0.77, "female": 0.23 },
"language_ratio": { "en": 0.77, "fr": 0.23 },
"emotion_ratio": { "neutral": 0.46, "joy": 0.28, "anger": 0.16, "sad": 0.06, "fear": 0.04 }
}
}