Skip to main content

Speaker Verification API

Compare a reference and a candidate audio clip and get a same-speaker verdict, a similarity score, and audio metadata for both files.

Base URL​

https://api.genderrecognition.com

Endpoint​

POST /v1/speaker-verification/api

Headers​

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

Body​

FieldTypeRequiredDescription
referencefileYesThe known speaker's voice to verify against.
candidatefileYesThe voice you want to check against the reference.

Example​

curl -X POST "https://api.genderrecognition.com/v1/speaker-verification/api" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@audio.wav"

Response​

{
  "success": true,
  "same_speaker": true,
  "similarity": 87,
  "threshold": 70,
  "reference_audio": {
    "duration": 4.8,
    "sample_rate": 16000
  },
  "candidate_audio": {
    "duration": 5.1,
    "sample_rate": 16000
  },
  "remainingRequests": 119
}

Response fields​

FieldTypeDescription
successbooleantrue when both clips were processed successfully.
same_speakerbooleantrue when similarity is at or above threshold, meaning the two clips are judged to be the same speaker.
similarityintegerHow closely the two voices match, 0-100. Higher means more similar.
thresholdintegerThe similarity cutoff used to decide same_speaker, 0-100. A similarity at or above this value is treated as a match.
reference_audio.durationnumberDuration of the reference clip in seconds, as decoded for comparison.
reference_audio.sample_ratenumberSample rate (Hz) the reference clip was decoded to before comparison.
candidate_audio.durationnumberDuration of the candidate clip in seconds, as decoded for comparison.
candidate_audio.sample_ratenumberSample rate (Hz) the candidate clip was decoded to before comparison.
remainingRequestsintegerAPI requests remaining after this successful request is deducted.

similarity and threshold are whole-number percentages, not raw scores.

Error cases​

Missing API key​

{ "error": "API key is required" }

Invalid API key​

{ "error": "Invalid API key" }

Missing file(s)​

{ "error": "Both reference and candidate files are required" }

File too large​

{ "error": "File too large" }

Unexpected field​

Returned when a file is uploaded under a field name other than reference or candidate (for example, using file, or sending an extra file):

{ "error": "Unexpected field" }

Invalid file type​

{
  "error": "Invalid file type. Allowed formats: WAV, MP3, FLAC, MP4, OGG, AIFF"
}

Audio conversion failed​

Returned when a file has an allowed extension but ffmpeg cannot convert it (for example, a corrupt or unreadable file):

{ "error": "Audio conversion failed: <details>" }

Quota exceeded​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Processing failed​

{ "error": "Speaker verification failed" }

Notes​

  • The backend accepts many common audio formats, including WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF, AU, and more, and converts non-WAV files before analysis.
  • Both uploads use the reference and candidate fields and must each be 10 MB or smaller.
  • The reference and candidate clips are processed independently, so they can differ in length, sample rate, and format.
  • A request is deducted only after verification completes successfully.